branches and tags

branches in sublimated are scoped to the folder level where they're created. this follows from hierarchical versioning — since every folder has its own commit history, branches belong to folders too.

folder-scoped branches

create a branch on docs/markdown:

git clone https://sublimated.com/docs/markdown.git
cd markdown
git checkout -b draft
# make changes
git push -u origin draft

the draft branch now exists at the markdown/ level:

• cloning docs/markdown — you see draft

• cloning docs — you do NOT see draft

branches don't leak up the tree. each folder is its own scope.

merging

when you merge a scoped branch back into main:

git checkout main
git merge draft
git push

the merge commit is created at the markdown/ level. then the cascade kicks in — commits propagate up to docs/ (space root) on the default branch.

the scoped branch stays at its level. the merged changes flow up.

tags

lightweight and annotated tags both work:

git tag v1.0
git push origin v1.0


# annotated
git tag -a v2.0 -m "release 2.0"
git push origin v2.0

tags are immutable. updating a tag requires --force.

use cases

• draft branches — work on a draft in docs/markdown/, invisible to people cloning the whole docs space

• feature branches — develop in a subfolder, merge when ready, changes cascade to root

• experiment branches — try something in a folder, delete the branch if it doesn't work out

• agent branches — an AI works on agent/* branches scoped to its folder, reviewed before merge

see git overview for how to clone and push, or hierarchical versioning for how the cascade works.