Deep Review: 20260501-221035-pr-4917

	syncExcludes, err := flags.GetStringArray("sync-exclude")
	if err != nil {
		return fmt.Errorf("failed to get sync-exclude flag: %w", err)
	}
	if len(syncExcludes) > 0 && !syncHostWorkdir {
		return errors.New("cannot use `--sync-exclude` without `--sync`")
	}

	// When workDir is explicitly set, the shell MUST have workDir as the cwd, or exit with an error.
	//
	// changeDirCmd := "cd workDir || exit 1"                  if workDir != ""
	//              := "cd hostCurrentDir || cd hostHomeDir"   if workDir == ""

This is the user-visible contract introduced by the PR but has no Go-level or BATS coverage. A regression that drops or inverts the guard would not be caught. Add a BATS case (limactl shell --sync-exclude=foo $INSTANCE -- true asserting the error) or extract the check into a helper that can be unit-tested.

func buildSyncExcludeArgs(excludes []string, syncDir string) []string {
	var args []string
	for _, pattern := range excludes {
		args = append(args, "--exclude", pattern)
	}
	ignoreFile := filepath.Join(syncDir, ".limasyncignore")
	if _, err := os.Stat(ignoreFile); err == nil {
		args = append(args, "--exclude-from", ignoreFile)
	}
	return args
}

// validateSyncFlagValue ensures the value passed to --sync is a directory
// path and not another flag token like "--sync-exclude=...".

If .limasyncignore exists but os.Stat fails for a reason other than ENOENT (permission denied, broken symlink, I/O error), the file is silently ignored and the sync quietly stops respecting the user's excludes.

Fix: skip on errors.Is(err, fs.ErrNotExist), log a warning otherwise so the operator can diagnose.

ignoreFile := filepath.Join(syncDir, ".limasyncignore")
switch _, err := os.Stat(ignoreFile); {
case err == nil:
    args = append(args, "--exclude-from", ignoreFile)
case errors.Is(err, fs.ErrNotExist):
    // no ignore file
default:
    logrus.WithError(err).Warnf("ignoring %s due to stat error", ignoreFile)
}

	return &s
}

// buildSyncExcludeArgs converts --sync-exclude flag values and an optional
// .limasyncignore file into rsync --exclude / --exclude-from arguments.
func buildSyncExcludeArgs(excludes []string, syncDir string) []string {
	var args []string
	for _, pattern := range excludes {
		args = append(args, "--exclude", pattern)
	}
	ignoreFile := filepath.Join(syncDir, ".limasyncignore")
	if _, err := os.Stat(ignoreFile); err == nil {
		args = append(args, "--exclude-from", ignoreFile)
	}
	return args
}

// validateSyncFlagValue ensures the value passed to --sync is a directory
// path and not another flag token like "--sync-exclude=...".
func validateSyncFlagValue(syncDirVal string) error {
	if syncDirVal != "" && strings.HasPrefix(syncDirVal, "--") {

The current implementation snapshots the host-side .limasyncignore at startup and embeds its absolute path into the rsync arguments reused for both the host→guest sync and the guest→host sync-back. Two consequences:

• An ignore file created or modified inside the guest during the shell session is never honored on the way back, because rsync still reads the host-side path.
• If the user deletes the host-side .limasyncignore mid-session, the cached --exclude-from argument now points at a missing file, causing both getRsyncStats and the eventual rsyncBack() to fail. The pre-existing unconditional defer cleanup at cmd/limactl/shell.go:480-485 then rm -rfs the guest workdir regardless. The data-loss-on-failure behavior is pre-existing and not a regression of this PR (verified at MERGE_BASE 898ac652), but the new code adds a contrived trigger.

		}
		logrus.Info("Successfully synced back the changes to host.")
		return nil
	}

	defer func() {
		// Clean up the guest synced workdir
		if err := executeSSHForRsync(ctx, *sshCmd, inst.SSHLocalPort, inst.SSHAddress, fmt.Sprintf("rm -rf %s", dirForCleanup)); err != nil {
			logrus.WithError(err).Warn("Failed to clean up guest synced workdir")
		}
	}()

	if !tty {
		return rsyncBack()
	}

Fix: replace the static --exclude-from with rsync's per-directory merge filter, which evaluates the ignore file dynamically at the root of the transfer and tolerates a missing file:

args = append(args, "--filter", ":- /.limasyncignore")

This also eliminates the empty-string placeholder dance in TestBuildSyncExcludeArgs and consolidates host- and guest-side semantics. The unconditional cleanup defer is a separate, pre-existing concern worth tracking independently.

### Excluding files or directories from syncing

 | ⚡ Requirement | Lima >= 2.2 |
 |----------------|-------------|

In addition to the `--sync` flag, a `--sync-exclude` flag is available, which allows you to configure directories that will not be synced to the VM. This is useful to exclude large generated directories (like `node_modules`, or `vendor`),
or more sensitive files (like credentials, or a `.git` directory). This flag can be repeated to exclude multiple directories.

The flag is passed to **rsync** as `--exclude` and must conform to its conventions.

```bash
limactl shell --sync . --sync-exclude .git default
```

The example in the same section uses *.o, which is a glob, not a directory. The docs should say "files or patterns" (or just "patterns") and link the rsync --exclude FILTER RULES section so users know which globbing conventions apply. The .limasyncignore block is missing a note on precedence: file and flag are additive — both apply if both are present.

	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			dir := t.TempDir()
			if tt.hasIgnore {
				ignoreFile := filepath.Join(dir, ".limasyncignore")
				err := os.WriteFile(ignoreFile, []byte("build\ndist\n"), 0o644)
				assert.NilError(t, err)
				// Patch expected with actual path
				for i, v := range tt.expected {
					if v == "" {
						tt.expected[i] = ignoreFile
					}
				}
			}
			got := buildSyncExcludeArgs(tt.excludes, dir)
			assert.DeepEqual(t, got, tt.expected)
		})
	}
}

The empty-string sentinel exists because t.TempDir() is unknown at table-declaration time, but the in-place patch is fragile: a future refactor that runs subtests in parallel, or one that shares tt.expected across cases, would silently corrupt fixtures. Build expected from explicit fields (e.g., wantPatterns []string, wantIgnore bool) and compute the final []string inside the subtest body.

		sshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)
	}
	sshArgs := append([]string{}, sshExe.Args...)
	sshArgs = append(sshArgs, sshutil.SSHArgsFromOpts(sshOpts)...)

	var (
		sshExecForRsync *exec.Cmd
		rsync           copytool.CopyTool
		excludeArgs     []string
	)
	if syncHostWorkdir {
		logrus.Infof("Syncing host current directory(%s) to guest instance...", hostCurrentDir)
		sshExecForRsync = exec.CommandContext(ctx, sshExe.Exe, sshArgs...)

		// Create the destination directory in the guest instance,

excludeArgs is now threaded through askUserForRsyncBack and getRsyncStats solely to be re-appended to a fresh copytool.Options. Two reasonable cleanups: reuse the existing rsync CopyTool for the dry-run inside getRsyncStats (with per-call options for --dry-run --itemize-changes), or wrap source/dest/AdditionalArgs into a single struct. As-is, askUserForRsyncBack now takes nine positional parameters and any future caller that forgets excludeArgs will produce stats that disagree with the actual sync.

// validateSyncFlagValue ensures the value passed to --sync is a directory
// path and not another flag token like "--sync-exclude=...".
func validateSyncFlagValue(syncDirVal string) error {
	if syncDirVal != "" && strings.HasPrefix(syncDirVal, "--") {
		return fmt.Errorf("--sync flag requires a directory path argument, got %q instead\nUsage: limactl shell --sync <DIR> [--sync-exclude <PATTERN>...] <INSTANCE> [COMMAND...]", syncDirVal)
	}
	return nil
}

func hasMetadataDelta(attrs string) bool {

The hardcoded usage line will drift from cobra's generated help the first time the flag set changes. Drop the second sentence and rely on limactl shell --help:

return fmt.Errorf("--sync flag requires a directory path argument, got %q instead", syncDirVal)