.gitignore and .saggar

Commit the parts of .saggar that describe the project. Ignore the files that describe one Mac. This keeps project setup useful to teammates and coding agents without leaking local state into the repository.

The recommended .gitignore rule

Add these lines to the project's .gitignore:

.saggar/**/*.local.*
.saggar/scratchpad.md

Saggar offers to add the rule when it first writes local project state. The pattern follows Saggar's naming convention: a file with .local. in its basename belongs to one machine. The scratchpad rule keeps temporary notes and handoff context in the checkout where they were written. Together, the rules leave shared configuration visible.

What to commit

Path	What it contains
.saggar/project.json	The project name, emoji, and documentation folder.
.saggar/commands.md	Shared commands and the project's startup set.
.saggar/jobs/*.json	Scheduled jobs, one reviewable file per job.

These files are plain JSON or Markdown. They should clone with the project, remain visible in diffs, and be available to anyone working in the repository. See Commands, startups, and jobs for their formats and how Saggar uses them.

What not to commit

Don't commit .saggar/scratchpad.md, .saggar/state.local.json, or any other .local. file under .saggar. They hold working or machine-local state and can change independently in every checkout.

User-wide Saggar data lives in ~/.saggar, outside the project. It includes app settings, terminal snapshots, agent presence data, and audit records. Don't copy that directory into a repository. Account and remote-control credentials remain in the macOS Keychain.

Avoid broad ignore rules

Don't ignore .saggar/, .saggar/**, or every hidden directory. Those rules also hide the shared files above, so changes to project setup can disappear from git status. Saggar warns when a broad rule masks shared configuration.

To find the rule responsible for an ignored path, ask Git:

git check-ignore -v .saggar/project.json

Remove or narrow the broad rule, then keep only the recommended local pattern. If a local file was committed before the ignore rule existed, stop tracking it without deleting your local copy:

git rm --cached .saggar/state.local.json

Commit the .gitignore change and the index removal together. Other checkouts will remove the tracked copy while Saggar can continue to maintain a fresh local file on each Mac.