docs: explain Git branches and tags (closes #279)

coding-practices/version-control-and-collaboration.qmd

@@ -1,3 +1,59 @@
+### Git Branches and Tags {#sec-git-branches-and-tags}
+
+To understand how Git tracks history,
+think of commits as Polaroid snapshots of your repository
+connected to their parent snapshots by strings.
+Branches and tags are both labels (like sticky notes)
+pointing to specific snapshots in this history graph:
+
+- **Branches are movable labels**:
+  A branch label points to the latest commit in a line of development.
+  When you make a new commit while working on a branch,
+  Git automatically advances the branch label forward to point to the new commit.
+  Think of a branch as a sticky note that moves automatically as history grows.
+- **Tags are permanent labels**:
+  A tag marks a specific point in time
+  (such as a published release like `v1.0.0` or a manuscript submission).
+  Tags do not move when new commits are added;
+  they remain anchored to their specific commit.
+  Git provides two types of tags:
+  *lightweight tags* (simple references directly pointing to a commit)
+  and *annotated tags* (full Git objects storing a tagger identity,
+  timestamp,
+  and release message;
+  recommended for official versions and public releases).
+
+For deeper background on Git's object model and branching mechanisms,
+consult the official
+[Git Branching in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell)
+and [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
+guides in *Pro Git* by Scott Chacon and Ben Straub.
+
+#### Practical branch and tag commands
+
+```bash
+# Create and switch to a new feature branch
+git switch -c feat/new-analysis
+
+# Publish the feature branch to GitHub and set upstream tracking
+git push -u origin feat/new-analysis
+
+# View all local and remote-tracking branches
+git branch -a
+
+# Create a lightweight tag at the current commit
+git tag v0.1.0
+
+# Create an annotated tag with a release message (recommended for releases)
+git tag -a v1.0.0 -m "Release version 1.0.0"
+
+# Push a specific tag to GitHub
+git push origin v1.0.0
+
+# Push reachable annotated tags alongside branch commits (safer than pushing all tags)
+git push --follow-tags
+```
+
 ### Version Numbers
 
 Follow semantic versioning (MAJOR.MINOR.PATCH):

inst/WORDLIST

@@ -16,6 +16,7 @@ CLI
 CLIs
 CONSORT
 Catalina
+Chacon
 ChatGPT
 CircleCI
 Codeberg
@@ -81,6 +82,7 @@ PII
 Padova
 Paratyphi
 Pokpongkiat
+Polaroid
 Posit
 PowerShell
 Powerlevel
@@ -96,6 +98,7 @@ ServiceNow
 Shigella
 Sixel
 Starship
+Straub
 TOCTOU
 TOML
 TUI