shell: Add sync-exclude flag and .limasyncignore file

To avoid syncing generated or sensitive data into a vm, a new sync-exclude flag
is added, to be used in conjunction with --sync. This allows to specify rsync excludes
which are then not synced.

Additionally a .limasyncignore file can be created, which also considered and
passed to rsync as the exclude-from flag.

Signed-off-by: Mathias Petermann <mathias.petermann@gmail.com>

Author: peschmae

cmd/limactl/shell.go

@@ -73,6 +73,7 @@ func newShellCommand() *cobra.Command {
 	shellCmd.Flags().Bool("preserve-env", false, "Propagate environment variables to the shell")
 	shellCmd.Flags().Bool("start", false, "Start the instance if it is not already running")
 	shellCmd.Flags().String("sync", "", "Copy a host directory to the guest and vice-versa upon exit")
+	shellCmd.Flags().StringArray("sync-exclude", nil, "Exclude pattern for --sync (can be specified multiple times)")
 
 	return shellCmd
 }
@@ -196,10 +197,22 @@ func shellAction(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("failed to get sync flag: %w", err)
 	}
 	syncHostWorkdir := syncDirVal != ""
+	// Validate that --sync has a proper directory value, not another flag
+	if err := validateSyncFlagValue(syncDirVal); err != nil {
+		return err
+	}
 	if syncHostWorkdir && len(inst.Config.Mounts) > 0 {
 		return errors.New("cannot use `--sync` when the instance has host mounts configured, start the instance with `--mount-none` to disable mounts")
 	}
 
+	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 != ""
@@ -354,6 +367,7 @@ func shellAction(cmd *cobra.Command, args []string) error {
 	var (
 		sshExecForRsync *exec.Cmd
 		rsync           copytool.CopyTool
+		excludeArgs     []string
 	)
 	if syncHostWorkdir {
 		logrus.Infof("Syncing host current directory(%s) to guest instance...", hostCurrentDir)
@@ -380,12 +394,13 @@ func shellAction(cmd *cobra.Command, args []string) error {
 			hostCurrentDir,
 			fmt.Sprintf("%s:%s", inst.Name, destRsyncDir),
 		}
+		excludeArgs = buildSyncExcludeArgs(syncExcludes, hostCurrentDir)
 		rsync, err = copytool.New(ctx, string(copytool.BackendRsync), paths, &copytool.Options{
 			Recursive: true,
 			Verbose:   false,
-			AdditionalArgs: []string{
+			AdditionalArgs: append([]string{
 				"--delete",
-			},
+			}, excludeArgs...),
 		})
 		if err != nil {
 			return err
@@ -439,12 +454,12 @@ func shellAction(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return err
 		}
-		return askUserForRsyncBack(ctx, cmd, inst, sshExecForRsync, hostCurrentDir, destRsyncDir, rsync, tty)
+		return askUserForRsyncBack(ctx, cmd, inst, sshExecForRsync, hostCurrentDir, destRsyncDir, rsync, tty, excludeArgs)
 	}
 	return nil
 }
 
-func askUserForRsyncBack(ctx context.Context, cmd *cobra.Command, inst *limatype.Instance, sshCmd *exec.Cmd, hostCurrentDir, destRsyncDir string, rsync copytool.CopyTool, tty bool) error {
+func askUserForRsyncBack(ctx context.Context, cmd *cobra.Command, inst *limatype.Instance, sshCmd *exec.Cmd, hostCurrentDir, destRsyncDir string, rsync copytool.CopyTool, tty bool, excludeArgs []string) error {
 	remoteSource := fmt.Sprintf("%s:%s", inst.Name, destRsyncDir)
 	clean := filepath.Clean(hostCurrentDir)
 	dirForCleanup := shellescape.Quote(filepath.Join(*inst.Config.User.Home, clean))
@@ -473,7 +488,7 @@ func askUserForRsyncBack(ctx context.Context, cmd *cobra.Command, inst *limatype
 		return rsyncBack()
 	}
 
-	rawOutput, stats, err := getRsyncStats(ctx, remoteSource, filepath.Dir(hostCurrentDir))
+	rawOutput, stats, err := getRsyncStats(ctx, remoteSource, filepath.Dir(hostCurrentDir), excludeArgs)
 	if err != nil {
 		logrus.WithError(err).Warn("failed to get rsync stats")
 	}
@@ -742,16 +757,16 @@ func (s *rsyncStats) String() string {
 	return fmt.Sprintf("added: %d, deleted: %d, modified: %d, metadata: %d", s.Added, s.Deleted, s.Modified, s.Metadata)
 }
 
-func getRsyncStats(ctx context.Context, source, destination string) (string, *rsyncStats, error) {
+func getRsyncStats(ctx context.Context, source, destination string, excludeArgs []string) (string, *rsyncStats, error) {
 	paths := []string{source, destination}
 	rsync, err := copytool.New(ctx, string(copytool.BackendRsync), paths, &copytool.Options{
 		Verbose: true,
-		AdditionalArgs: []string{
+		AdditionalArgs: append([]string{
 			"--dry-run",
 			"--itemize-changes",
 			"-ah",
 			"--delete",
-		},
+		}, excludeArgs...),
 	})
 	if err != nil {
 		return "", nil, err
@@ -822,6 +837,29 @@ func parseRsyncStats(output string) *rsyncStats {
 	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, "--") {
+		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 {
 	for _, ch := range attrs {
 		if ch != '.' {

cmd/limactl/shell_test.go

@@ -4,11 +4,69 @@
 package main
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 
 	"gotest.tools/v3/assert"
 )
 
+func TestBuildSyncExcludeArgs(t *testing.T) {
+	tests := []struct {
+		name      string
+		excludes  []string
+		hasIgnore bool
+		expected  []string
+	}{
+		{
+			name:     "empty excludes, no ignore file",
+			excludes: nil,
+			expected: nil,
+		},
+		{
+			name:     "single exclude",
+			excludes: []string{"node_modules"},
+			expected: []string{"--exclude", "node_modules"},
+		},
+		{
+			name:     "multiple excludes",
+			excludes: []string{"node_modules", ".git", "vendor"},
+			expected: []string{"--exclude", "node_modules", "--exclude", ".git", "--exclude", "vendor"},
+		},
+		{
+			name:      "ignore file only",
+			excludes:  nil,
+			hasIgnore: true,
+			expected:  []string{"--exclude-from", ""}, // placeholder, patched below
+		},
+		{
+			name:      "excludes and ignore file",
+			excludes:  []string{".git"},
+			hasIgnore: true,
+			expected:  []string{"--exclude", ".git", "--exclude-from", ""}, // placeholder
+		},
+	}
+
+	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)
+		})
+	}
+}
+
 func TestParseRsyncStats(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -68,6 +126,16 @@ cL+++++++++ new-symlink -> target
 	}
 }
 
+func TestValidateSyncFlagValue(t *testing.T) {
+	// When the sync value looks like another flag, validation should return an error
+	err := validateSyncFlagValue("--sync-exclude=.git")
+	assert.ErrorContains(t, err, "--sync flag requires a directory path")
+
+	// When the sync value is a normal directory, validation should pass
+	err = validateSyncFlagValue(".")
+	assert.NilError(t, err)
+}
+
 func TestRsyncStatsString(t *testing.T) {
 	tests := []struct {
 		name     string

website/content/en/docs/examples/ai.md

@@ -185,6 +185,33 @@ limactl shell --sync . default
 - **No**: Discards changes and cleans up guest directory
 - **View the changed contents**: Shows a diff of changes made by the agent
 
+### 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
+```
+
+Alternatively a `.limasyncignore` file can be created in the target directory, which contains a list of excludes.
+
+```
+node_modules
+.git
+vendor
+build
+dist
+*.o
+```
+
+If this file exists, it is automatically passed to **rsync** as `--exclude-from`.
+
 ### Requirements
 
 - **rsync** must be installed on both host and guest