feat: auto-update .gitignore with synced symlink entries

- sync command appends symlink targets to .gitignore if missing
- Adds header comment '# sync-agents (generated symlinks)'
- Idempotent: never duplicates entries
- Respects --targets (only adds relevant entries)
- Respects --dry-run (shows what would be added)
- Preserves existing .gitignore content

Author: nmccready

src/sh/sync-agents.sh

@@ -315,9 +315,65 @@ cmd_sync() {
     create_symlink "$AGENTS_MD" "$PROJECT_ROOT/CLAUDE.md" "$DRY_RUN"
   fi
 
+  # Update .gitignore with synced symlink entries
+  update_gitignore
+
   info "Sync complete."
 }
 
+# --------------------------------------------------------------------------
+# .gitignore management
+# --------------------------------------------------------------------------
+
+update_gitignore() {
+  local gitignore="$PROJECT_ROOT/.gitignore"
+
+  # Build list of entries that should be ignored (synced symlinks)
+  local entries=()
+  for target in "${ACTIVE_TARGETS[@]}"; do
+    local target_dir
+    target_dir="$(resolve_target_dir "$target" "$PROJECT_ROOT")"
+    local rel_path="${target_dir#"$PROJECT_ROOT"/}/"
+    entries+=("$rel_path")
+  done
+  entries+=("CLAUDE.md")
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    for entry in "${entries[@]}"; do
+      if [[ ! -f "$gitignore" ]] || ! grep -qxF "$entry" "$gitignore"; then
+        echo "  would add to .gitignore: $entry"
+      fi
+    done
+    return 0
+  fi
+
+  # Create .gitignore if it doesn't exist
+  [[ -f "$gitignore" ]] || touch "$gitignore"
+
+  local added=0
+  for entry in "${entries[@]}"; do
+    if ! grep -qxF "$entry" "$gitignore"; then
+      # Add sync-agents header on first addition
+      if [[ "$added" -eq 0 ]]; then
+        # Check if header already exists
+        if ! grep -qF "# sync-agents" "$gitignore"; then
+          # Add a blank line separator if file is non-empty
+          if [[ -s "$gitignore" ]]; then
+            echo "" >> "$gitignore"
+          fi
+          echo "# sync-agents (generated symlinks)" >> "$gitignore"
+        fi
+      fi
+      echo "$entry" >> "$gitignore"
+      added=$((added + 1))
+    fi
+  done
+
+  if [[ "$added" -gt 0 ]]; then
+    info "Added $added entries to .gitignore"
+  fi
+}
+
 cmd_status() {
   echo -e "${BOLD}sync-agents${RESET} v${VERSION}"
   echo ""

test/sync-agents.bats

@@ -588,6 +588,60 @@ teardown() {
   [ ! -d "$TEST_DIR/.windsurf" ]
 }
 
+# --------------------------------------------------------------------------
+# .gitignore
+# --------------------------------------------------------------------------
+
+@test "sync adds symlink entries to .gitignore" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  bash "$SCRIPT" -d "$TEST_DIR" sync
+  [ -f "$TEST_DIR/.gitignore" ]
+  grep -qxF ".claude/" "$TEST_DIR/.gitignore"
+  grep -qxF ".windsurf/" "$TEST_DIR/.gitignore"
+  grep -qxF ".cursor/" "$TEST_DIR/.gitignore"
+  grep -qxF ".github/copilot/" "$TEST_DIR/.gitignore"
+  grep -qxF "CLAUDE.md" "$TEST_DIR/.gitignore"
+}
+
+@test "sync adds header comment to .gitignore" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  bash "$SCRIPT" -d "$TEST_DIR" sync
+  grep -qF "# sync-agents" "$TEST_DIR/.gitignore"
+}
+
+@test "sync does not duplicate .gitignore entries" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  bash "$SCRIPT" -d "$TEST_DIR" sync
+  bash "$SCRIPT" -d "$TEST_DIR" sync
+  local count
+  count=$(grep -cxF "CLAUDE.md" "$TEST_DIR/.gitignore")
+  [ "$count" -eq 1 ]
+}
+
+@test "sync preserves existing .gitignore content" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  echo "node_modules/" > "$TEST_DIR/.gitignore"
+  bash "$SCRIPT" -d "$TEST_DIR" sync
+  grep -qxF "node_modules/" "$TEST_DIR/.gitignore"
+  grep -qxF "CLAUDE.md" "$TEST_DIR/.gitignore"
+}
+
+@test "sync --targets only adds relevant entries to .gitignore" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  bash "$SCRIPT" -d "$TEST_DIR" sync --targets claude
+  grep -qxF ".claude/" "$TEST_DIR/.gitignore"
+  grep -qxF "CLAUDE.md" "$TEST_DIR/.gitignore"
+  ! grep -qxF ".windsurf/" "$TEST_DIR/.gitignore"
+}
+
+@test "sync --dry-run does not modify .gitignore" {
+  bash "$SCRIPT" -d "$TEST_DIR" init
+  bash "$SCRIPT" -d "$TEST_DIR" sync --dry-run
+  if [ -f "$TEST_DIR/.gitignore" ]; then
+    ! grep -qxF "CLAUDE.md" "$TEST_DIR/.gitignore"
+  fi
+}
+
 # --------------------------------------------------------------------------
 # Inheritance
 # --------------------------------------------------------------------------