Branches and pull requests

Give a line of work a name

A branch is a movable reference to a commit. When you commit on that branch, its reference advances. Switching branches changes which snapshot is checked out; a branch is not another full copy of your directory. This makes a short branch useful for reviewing a runbook change before including it in the main line of work.

Use the disposable repository from the preceding bite, with clean status. If you opened a new terminal, cd to its recorded path. Do not start inside a repository containing unrelated work.

git status --short
git branch --show-current
study_base=$(git branch --show-current)
git switch -c docs/recovery-notes
printf '\nRecovery: preserve evidence before retrying.\n' >> runbook.md
git add runbook.md
git diff --cached
git commit -m 'Document recovery evidence'
git log --oneline --decorate -3
git diff "$study_base"...HEAD

study_base remembers the actual original branch name rather than assuming main. The three-dot diff shows what changed since the branches' common ancestor. Expect the added recovery line. The original branch still names its older commit; your feature branch names the new one. HEAD follows the feature branch while you are on it.

Compare, then integrate

In this fixture no one else has advanced the original branch. Integrate the reviewed change locally:

git switch "$study_base"
git log --oneline -1
git merge --ff-only docs/recovery-notes
git log --oneline --decorate -3
git status --short

A fast-forward moves the original branch reference along the already existing line of commits; no merge commit is needed. --ff-only refuses if the histories have diverged, giving you a chance to inspect instead of choosing an integration strategy silently. Keep the feature branch for now.

When both branches have new commits, a normal merge can create a commit with two parents, preserving both histories. A rebase instead replays selected changes onto a new base as new commits with new IDs. Rewriting a branch that others already use requires coordination. A conflict means Git cannot decide the intended combined content; remove conflict markers only after choosing that content and checking it. git merge --abort or git rebase --abort can abandon the respective in-progress operation.

How a local branch becomes a review

A remote is a named repository location, often called origin. A remote-tracking reference such as origin/main is your local record of its last observed branch state. It is not live knowledge of what another person just pushed.

No remote or publication is needed here. Draft a review description for the local diff: “The runbook omitted what to preserve before a retry. This adds an evidence step. I checked the final text and diff; it does not execute recovery.” That is more useful than an unexplained “docs update.” A green CI badge reports the configured checks; reviewers still assess intent, assumptions, and missing checks.

For the personal site, short branches with reviewed changes are sufficient. Release branches for several supported product versions and GitFlow's extra long-lived branches solve different collaboration needs; do not add them without that need. Tags can name a release snapshot, while a branch normally continues moving.

Why did the merge above create no extra commit? The original branch had not diverged, so advancing its reference was enough. Why is origin/main potentially stale? It changes when your repository communicates with the remote. Next, practice reversing a change while preserving the explanation in history.

Sources

Primary references: Git branching basics↗; About pull requests↗.