diff --git a/coding-practices/version-control-and-collaboration.qmd b/coding-practices/version-control-and-collaboration.qmd index f7e7dece..c5841c80 100644 --- a/coding-practices/version-control-and-collaboration.qmd +++ b/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): diff --git a/inst/WORDLIST b/inst/WORDLIST index 3ef19674..ab1da49e 100644 --- a/inst/WORDLIST +++ b/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