Version Control Setup

Updated on Oct 1, 2026

This page explains which Forge files to commit and which to add to .gitignore. It helps you share configuration with your team without committing credentials, lock files, or machine-specific artifacts.

What to commit

Path	Contents	Recommendation
`.forge/config/`	`project.toml`, `agents.toml`, `toolchain.toml`, `commands.toml`, `workflows/`	Commit, except `telemetry.toml` and `opensearch.toml`
`.forge/prompts/`	Custom prompt templates	Commit
`.agents/skills/`	Agent skills	Commit
`.forge/.config_lock`	Configuration lock created by `frg config lock`	Commit when your team uses drift detection
`.forge/work/`	Job outputs: plans, reviews, traces, sessions, approvals	Team decision
`.forge/context.toml`	Current issue, PR, ticket, service, and user identity	Developer-specific; consider ignoring
`.forge/cache/`, `.forge/logs/`	Cache and utility logs	Ignore
`.forge/.context.lock`, `.forge/.workflow.lock`	Runtime locks	Ignore
`.forge/license/`	License files	Ignore

Recommended .gitignore

frg config init prints these patterns. Add them to your .gitignore, together with .forge/license/:

gitignore

# Forge
.forge/logs/
.forge/cache/
.forge/.context.lock
.forge/.workflow.lock
.forge/work/**/traces/.heartbeat
.forge/config/opensearch.toml
.forge/config/telemetry.toml
.forge/license/

# Optional (team decision): job outputs
# .forge/work/

telemetry.toml and opensearch.toml can contain endpoint headers and API tokens. License files are issued per user or organization.

Decide about `.forge/work/`

Commit .forge/work/ when your team wants plans, reviews, and traces to be visible and auditable. Ignore it to keep the repository focused on source code, or when traces can contain sensitive context.

To commit plans and reviews but exclude session and approval state, add:

gitignore

.forge/work/**/sessions.toml
.forge/work/**/.sessions.lock
.forge/work/*/approvals/

Monorepos

If .forge/ directories exist below the repository root, prefix the patterns with **/:

gitignore

**/.forge/logs/
**/.forge/cache/
**/.forge/.context.lock
**/.forge/.workflow.lock
**/.forge/work/**/traces/.heartbeat
**/.forge/config/opensearch.toml
**/.forge/config/telemetry.toml
**/.forge/license/

Stop tracking files that are already committed

Add the patterns to .gitignore.
Remove the files from the index. Your local copies are kept.

bash

git rm -r --cached --ignore-unmatch .forge/logs/ .forge/cache/
git rm --cached --ignore-unmatch .forge/.context.lock .forge/.workflow.lock
git rm --cached --ignore-unmatch .forge/config/telemetry.toml .forge/config/opensearch.toml

Commit the change:

bash

git commit -m "chore: ignore Forge runtime files"

Remove credentials from history

Warning: Rewriting Git history is destructive. Coordinate with your team first.

git rm --cached does not remove a file from history. If you committed a token:

Revoke or rotate the token. Assume it is compromised.
Remove the file from history with BFG Repo-Cleaner or git filter-repo:

bash

bfg --delete-files telemetry.toml
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force