1# branches and tags
2
3branches in sublimated are scoped to the folder level where they're created. this follows from [hierarchical versioning](hierarchical.md) — since every folder has its own commit history, branches belong to folders too.
4
5## folder-scoped branches
6
7create a branch on `anton/blog/archive`:
8
9```bash
10git clone https://sublimated.com/anton/blog/archive.git
11cd archive
12git checkout -b draft
13# make changes
14git push -u origin draft
15```
16
17the `draft` branch now exists at the `archive/` level:
18- cloning `anton/blog/archive` — you see `draft`
19- cloning `anton/blog` — you do NOT see `draft`
20- cloning `anton` — you do NOT see `draft`
21
22branches don't leak up the tree. each folder is its own scope.
23
24## merging
25
26when you merge a scoped branch back into `main`:
27
28```bash
29git checkout main
30git merge draft
31git push
32```
33
34the merge commit is created at the `archive/` level. then the [cascade](hierarchical.md) kicks in — commits propagate up through `blog/` to `anton/` (space root) on the default branch.
35
36the scoped branch stays at its level. the merged changes flow up.
37
38## tags
39
40lightweight and annotated tags both work:
41
42```bash
43git tag v1.0
44git push origin v1.0
45
46# annotated
47git tag -a v2.0 -m "release 2.0"
48git push origin v2.0
49```
50
51tags are immutable. updating a tag requires `--force`.
52
53## use cases
54
55- **draft branches** — work on a blog post draft in `blog/posts/`, invisible to people cloning the whole blog
56- **feature branches** — develop a feature in `platform/api/`, merge when ready, changes cascade to root
57- **experiment branches** — try something in `data/analysis/`, delete the branch if it doesn't work out
58- **agent branches** — an AI works on `agent/*` branches scoped to its folder, reviewed before merge
59
60see [git overview](index.md) for how to clone and push, or [hierarchical versioning](hierarchical.md) for how the cascade works.