Git Subtree Manager
Manages git subtrees in the docs/ directory for AI agents to reference external library source code.
Current Subtrees
Library Directory Repository Branch
Effect docs/effect/
https://github.com/Effect-TS/effect.git
main
Tamagui docs/tamagui/
https://github.com/tamagui/tamagui.git
master
Better Auth docs/better-auth/
https://github.com/better-auth/better-auth.git
main
Effect Atom docs/effect-atom/
https://github.com/tim-smart/effect-atom.git
main
Adding a New Subtree
Prerequisites - CRITICAL
Working directory must be clean. Git subtree commands will fail or behave unexpectedly with uncommitted changes.
Before ANY subtree operation:
Check for uncommitted changes:
git status
If there are staged or unstaged changes, stash them:
git stash --include-untracked
Verify working directory is clean:
git status
Should show "nothing to commit, working tree clean"
Add Command
git subtree add --prefix=docs/<name> <repo-url> <branch> --squash
Example:
git subtree add --prefix=docs/better-auth https://github.com/better-auth/better-auth.git main --squash
Post-Add Updates
After adding a subtree, update these configuration files:
biome.json
- Add to files.includes :
"!docs/<name>",
.github/dependabot.yml
-
Add to exclude-paths :
-
"docs/<name>/**"
eslint.config.mjs
- Add to ignores :
'docs/<name>/**',
AGENTS.md
-
Add entry to the subtrees table
Relevant skills - Update .claude/skills/*/SKILL.md files that should reference the new subtree
Restore Stashed Changes - DON'T FORGET
After completing subtree operations and config updates:
git stash pop
Always verify the user's original changes are restored:
git status
Updating an Existing Subtree
Prerequisites - CRITICAL
Same as adding: stash any uncommitted changes first (see above).
To pull latest changes from upstream:
git subtree pull --prefix=docs/<name> <repo-url> <branch> --squash
Example:
git subtree pull --prefix=docs/effect https://github.com/Effect-TS/effect.git main --squash
Configuration Files Checklist
When adding/updating subtrees, ensure these files exclude the subtree directory:
-
biome.json
-
files.includes array
-
.github/dependabot.yml
-
exclude-paths array
-
eslint.config.mjs
-
ignores array
-
AGENTS.md
-
subtrees documentation table
-
Relevant .claude/skills/*/SKILL.md files
Troubleshooting
"working tree has modifications" Error
This means you forgot to stash changes. Do not proceed without stashing:
1. Stash all changes (including untracked files)
git stash --include-untracked
2. Run your subtree command
git subtree add/pull ...
3. IMPORTANT: Restore the user's changes
git stash pop
4. Verify changes are back
git status
Subtree Already Exists
If the directory already exists, remove it first (losing local changes):
rm -rf docs/<name> git add docs/<name> git commit -m "chore: remove docs/<name> for re-add"
Then run the add command again.