.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/jobs/

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 other rules keep temporary notes, handoff context, and scheduled tasks in the checkout where they were created. Together, the rules leave shared configuration visible.

What to commit

Path	What it contains
.saggar/project.json	The project's display name and documentation folder.
.saggar/commands.md	Shared commands and the project's startup set.

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 scheduled tasks for their formats and how Saggar uses them.

What not to commit

Don't commit .saggar/jobs/, .saggar/scratchpad.md, or any .local. file under .saggar. They hold working 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/scratchpad.md

Commit the .gitignore change and the index removal together. Other checkouts will remove the tracked copy while each checkout keeps its own local file.