> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync a local Git worktree to a cloud VM

> Sync a local Git worktree to a cloud VM using authoritative one-way sync, includes, exclusions, and exact deletes.

Before you sync a local Git worktree to a cloud VM, resolve any unmerged index entries. Your laptop is authoritative; managed commands copy selected inputs to `/workspace` before execution.

## What sync includes

Tracked files and nonignored untracked files are inputs. Use `sync.include` for safe ignored inputs and `sync.exclude` to narrow the selection:

```toml theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
[sync]
include = ["fixtures/generated/**"]
exclude = ["coverage/**"]
```

Patterns are root-relative Git wildmatch patterns. Negation and path traversal are rejected.

Resolve unmerged indexes, materialize sparse worktrees and exclude selected submodules and paths with Git filters, including LFS filters, before syncing. Files are limited to 256 MiB each, selected source bytes to 1 GiB and revision metadata to 3 MiB; add patterns to `sync.exclude` when selection exceeds these limits.

## Updates and deletes

Changed managed files are replaced. Exact deletes of previously managed paths propagate. Files created only on the guest, such as dependency caches and build outputs, survive source sync.

The CLI freezes source bytes in a private local cache. It reuses hashes only while file identity, size, high-resolution timestamps and mode still match. Guest managed files are verified on each sync. You can remove the local source cache to reclaim space or force a fresh scan.

## Excluded paths

Secret paths, raw Git data, control files and build-output directories do not sync. These include `.env*`, `.key` and `.pem` files, `.ssh`, cloud credential directories, package-manager auth files, `auth.json`, `credentials.json`, `target`, `node_modules` and `__pycache__`. Explicit includes cannot bypass those exclusions.

bead also scans selected file contents for recognized provider credentials. A match rejects sync; remove the credential or exclude the file before retrying.

Use [environment injection](https://docs.bead.run/worktrees/environment.md) for dotenv values and [artifact pulls](https://docs.bead.run/worktrees/exec.md) for build results.

## Git on the guest

The guest has `git init` and the selected files. History-dependent commands such as `git log` and `git describe` are unsupported. Version scripts can use `BEAD_GIT_COMMIT` and `BEAD_GIT_BRANCH`.

A dev invocation syncs once. To apply local edits, stop and start [the service](https://docs.bead.run/worktrees/services.md) again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.