Workflow · XB Field Notes

git stash saves work for later

Sat, 11 Dec 2027 00:00:00 +0000

Git stash records selected uncommitted work so a checkout can temporarily return to an earlier committed state. It is useful for a short interruption, but neither saving nor restoring is an unconditional promise about every file in the directory. The important questions are what was included, which base the work came from, what state the destination now has, and when the saved entry can be removed.

Know what the snapshot includes

An ordinary git stash push records tracked working-tree changes and the index, then rolls those changes back toward HEAD. Untracked files remain unless included with -u. Ignored files still remain with that option; -a includes ignored files too. Review the scope before selecting it, because ignored paths can contain credentials, large build outputs, or local data that should not enter Git objects.

Options for selected paths, staged changes, or keeping the index produce different results. Do not combine them by habit and assume they all describe the same snapshot. Inspect status and the intended diff first, give the entry a meaningful message, and inspect the saved contents before treating the original edits as recoverable.

A stash is represented by Git commit objects, not a special file outside the object database. The newest entry is referenced by refs/stash; older entries are retained through its reflog. They are not necessarily shown by ordinary branch history. A forgotten entry is not automatically lost, but deleting its retention references can eventually make recovery impossible. A local branch or stash also does not by itself provide an independent off-machine backup.

Applying is different from popping

git stash apply attempts restoration and retains the saved entry. This is useful when the restored result must be reviewed before removing the saved copy. By default, do not expect the original staged versus unstaged distinction to be reinstated. --index additionally attempts to restore index state, which can fail if conflicts or destination changes prevent it.

git stash pop applies an entry and removes it from the list only when application succeeds. A conflicting pop retains the entry, but may already have changed cleanly applicable paths. A nonzero status therefore does not mean the entire operation left the working tree untouched. Inspect the index and files before trying another application.

Entries are not private to a branch or linked worktree. Their descriptive branch name is context, not a rule forcing restoration there. Numbered selectors can change as entries are added or dropped, so inspect and record the exact object before a sensitive operation. Quote selectors such as 'stash@{0}' when passing them through a shell.

When it breaks

Restoration onto a changed base can conflict or produce behavior that needs adaptation even without text conflicts. Resolve using the intended final code, stage the specific paths, and test the result. Do not repeatedly pop the same retained entry into a partially restored tree. Stash application has no general abort command that automatically reverses every partial effect.

When the original base is the right place to resume, git stash branch creates a branch there and applies the saved work. A successful application also drops an entry specified through the stash reflog. It is a recovery workflow tied to the recorded base, not a solution requiring two stashes or a particular elapsed time.

Removing an entry should follow verification, not substitute for it. Broad stash clear can discard unrelated saved work, and dropped objects may later be pruned. For work that needs ongoing review, make an intentional commit on a suitable branch and preserve it according to the project’s backup and sharing policy. Stash is not a promise to capture editor buffers, arbitrary filesystem metadata, or every external resource a build uses.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. All changes and removals happen in a disposable repository with example identity, disabled hooks and signing, excluded personal Git configuration and routing variables, and no remote. The fixture deliberately gives the index and working file different values.

import os
import subprocess
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-stash-demo-") as directory:
 root = Path(directory)
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Stash Example",
 "-c", "user.email=stash@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=root, env=env, text=True, capture_output=True, check=check,
 )
 git("init", "-q", "-b", "main")
 (root / ".gitignore").write_text("ignored.txt\n")
 (root / "note.txt").write_text("base\n")
 git("add", ".gitignore", "note.txt")
 git("commit", "-qm", "base")
 (root / "note.txt").write_text("staged\n")
 git("add", "note.txt")
 (root / "note.txt").write_text("working\n")
 (root / "new.txt").write_text("untracked\n")
 (root / "ignored.txt").write_text("ignored\n")
 git("stash", "push", "-qm", "tracked only")
 saved = git("rev-parse", "refs/stash").stdout.strip()
 print("default-leaves-untracked:", (root / "new.txt").exists()
 and (root / "ignored.txt").exists()
 and (root / "note.txt").read_text() == "base\n")
 git("stash", "apply", "--index", saved)
 restored = (git("show", ":note.txt").stdout == "staged\n"
 and (root / "note.txt").read_text() == "working\n")
 assert restored
 print("index-and-work-restored:", restored)
 print("apply-keeps-entry:", git("rev-parse", "stash@{0}").stdout.strip() == saved)
 assert git("rev-parse", "stash@{0}").stdout.strip() == saved
 git("stash", "drop", "-q", "stash@{0}")
 git("stash", "push", "-qu", "-m", "tracked and untracked")
 saved = git("rev-parse", "stash@{0}").stdout.strip()
 print("include-untracked-not-ignored:", not (root / "new.txt").exists()
 and (root / "ignored.txt").exists())
 (root / "note.txt").write_text("upstream\n")
 git("add", "note.txt")
 git("commit", "-qm", "new base")
 conflict = git("stash", "pop", "stash@{0}", check=False)
 print("conflicting-pop-keeps-entry:", conflict.returncode != 0
 and bool(git("ls-files", "-u").stdout)
 and git("rev-parse", "stash@{0}").stdout.strip() == saved)
 (root / "note.txt").write_text("upstream\nworking\n")
 git("add", "note.txt", "new.txt")
 assert not git("ls-files", "-u").stdout
 assert git("show", ":note.txt").stdout == "upstream\nworking\n"
 assert (root / "new.txt").read_text() == "untracked\n"
 git("commit", "-qm", "retain both fixture values")
 assert git("rev-parse", "stash@{0}").stdout.strip() == saved
 git("stash", "drop", "-q", "stash@{0}")
 print("resolved-and-verified:", not git("status", "--porcelain").stdout
 and not git("stash", "list").stdout)

All six checks should print True. The default leaves untracked and ignored files, while indexed application restores the two tracked states and retains the entry. Including untracked files still excludes the ignored file. A later conflicting pop retains its entry; the fixture explicitly resolves to both intended values, commits and verifies that result, then drops only the identified entry. Python finally removes all disposable data, including the ignored file.

Sources

Git stash reference, snapshot scope, stored entries, restoration, and removal semantics, checked 2026-09-07.
Pro Git: stashing and cleaning, index restoration and resuming work from its original base, checked 2026-09-07.

git cherry-pick re-applies a commit

Thu, 25 Nov 2027 00:00:00 +0000

Cherry-pick applies the change introduced by a selected commit to the current line of development. It is useful for a targeted backport when an older release needs one fix without the rest of a development branch. It does not move or delete the source commit, and it does not establish a merge relationship with the source branch. The target result must be reviewed as a change in its own environment.

Select a change relative to its parent

For an ordinary single-parent commit, the relevant change is the difference from that parent. Git uses the available history and merge machinery to apply that change to the target. It is not simply replacing the target files with the source’s complete snapshot. Other changes already present on the target should remain unless the selected change or its resolution deliberately affects them.

Usually, cherry-pick records a new commit after the target tip. Its parent and potentially its tree differ from the source, so its identity differs too. The original author identity and author date are normally retained, while the committer identifies whoever records the backport. The commit message need not change. Do not describe cherry-picking as automatically assigning a new author or inventing a new message.

The default creates commits, but --no-commit instead leaves changes in the index and working tree for review or combination. With --ff, an eligible operation can fast-forward to the existing source commit. These explicit modes are reasons not to assert that every possible cherry-pick invocation always creates a different object.

A backport needs dependency review

A fix can depend on an API, schema, configuration, or earlier refactoring absent from the target branch. Clean textual application does not establish behavioral correctness. Read the source change and its prerequisites, then test the affected behavior on the actual maintenance branch. Backport only the dependencies that the intended fix requires, with an explicit explanation of any adaptation.

For a clean pick between shared branches, -x records the source commit ID in the new message. That makes later tracing easier, but is not cryptographic proof of equivalence or approval. Review the final message after manual conflict resolution too. The original commit’s signature does not become a valid signature for a newly created object; any required target signature belongs to the target’s release process.

When it breaks

On a conflict, Git keeps HEAD at the last successfully created commit and records the problematic source in CHERRY_PICK_HEAD. Cleanly applied paths can already be updated, while conflicted paths have unmerged index entries. Conflict markers are useful for text files, but binary conflicts and other conflict types require inspecting status and the index rather than searching only for marker strings.

Resolve the intended target behavior, stage the specific resolved paths, and run the relevant tests before git cherry-pick --continue. A staged file means the conflict was marked resolved, not that the code is correct. --abort returns to the pre-sequence state; --quit forgets operation state without performing the same rollback. Start from a clean, understood working tree so aborting does not become a substitute for preserving unrelated work.

A change already present can make the pick empty. Determine whether the target really contains the intended behavior before skipping; a superficially similar patch may have different effects. Selecting a merge commit introduces another choice: -m identifies the numbered parent used as the mainline. Choosing a parent is a semantic decision about the desired difference, not a generic conflict bypass, and the result does not reproduce the original merge topology.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. The isolated temporary repository excludes personal Git configuration and inherited Git routing variables. It uses example identities, disables hooks and signing, and has no remote. One target accepts the fix; another deliberately edits the same line differently and exercises abort.

import os
import subprocess
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-pick-demo-") as directory:
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Backport Example",
 "-c", "user.email=backport@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=directory, env=env, text=True, capture_output=True, check=check,
 )
 def commit(text, message):
 (Path(directory) / "value.txt").write_text(text)
 git("add", "value.txt")
 git("commit", "-qm", message)
 git("init", "-q", "-b", "main")
 commit("old\n", "base")
 base = git("rev-parse", "HEAD").stdout.strip()
 git("switch", "-qc", "source")
 (Path(directory) / "value.txt").write_text("fixed\n")
 git("add", "value.txt")
 git("-c", "user.name=Original Example", "-c", "user.email=original@example.invalid",
 "commit", "-qm", "fix value")
 source = git("rev-parse", "HEAD").stdout.strip()
 git("switch", "-q", "main")
 git("commit", "--allow-empty", "-qm", "target progress")
 target = git("rev-parse", "HEAD").stdout.strip()
 git("cherry-pick", "-x", source)
 print("change-applied:", (Path(directory) / "value.txt").read_text() == "fixed\n")
 print("new-object-on-target:", git("rev-parse", "HEAD").stdout.strip() != source
 and git("rev-parse", "HEAD^").stdout.strip() == target)
 print("author-preserved:", git("show", "-s", "--format=%ae", "HEAD").stdout.strip()
 == "original@example.invalid")
 print("committer-is-backporter:", git("show", "-s", "--format=%ce", "HEAD").stdout.strip()
 == "backport@example.invalid")
 print("provenance-recorded:", source in git("show", "-s", "--format=%B", "HEAD").stdout)
 git("switch", "-qc", "conflict", base)
 commit("other\n", "target alternative")
 before = git("rev-parse", "HEAD").stdout.strip()
 conflict = git("cherry-pick", source, check=False)
 print("conflict-stopped:", conflict.returncode != 0
 and bool(git("ls-files", "-u").stdout)
 and git("rev-parse", "CHERRY_PICK_HEAD").stdout.strip() == source
 and git("rev-parse", "HEAD").stdout.strip() == before)
 git("cherry-pick", "--abort")
 print("abort-restored:", git("rev-parse", "HEAD").stdout.strip() == before
 and (Path(directory) / "value.txt").read_text() == "other\n"
 and not git("status", "--porcelain").stdout)

All seven checks should print True. The clean target contains the fixed value in a new commit whose parent is the target’s former tip. The source author remains, the backporter is the committer, and the message records provenance. The conflicting target stops with unmerged entries, then abort restores its prior text, tip, and clean status. This demonstrates transfer and recovery mechanics, not application-level correctness of a real backport.

Sources

Git cherry-pick reference, application modes, conflict state, and sequence controls, checked 2026-09-07.
Pro Git: maintaining a project, choosing individual changes for another line of development, checked 2026-09-07.

.gitignore controls untracked paths

Mon, 15 Nov 2027 00:00:00 +0000

Git ignore rules influence which untracked paths ordinary discovery and add operations consider. They are useful for generated files, editor state, and local configuration. They do not create an access-control boundary, remove a file already in the index, or erase earlier commits. Treat the ignore file as a project convention with observable matching rules, not as a guarantee that a sensitive file cannot enter history.

When it breaks

A rule added after a file was tracked does not stop tracking it. Changing that file and running an ordinary add can still stage the new content. This explains why adding a leaked configuration filename to .gitignore does not repair the leak. Index membership, current worktree contents, and historical blobs are distinct states that need separate inspection.

Negation is another common surprise. Ignoring an entire directory prevents Git from descending into it, so a later exception for one child cannot rescue that child. Ignore the directory’s contents while leaving its parent traversable, or explicitly restore every excluded parent before restoring a descendant. A nested ignore file cannot help if Git never visits that directory.

Precedence is not simply “the most specific-looking pattern wins.” Git defines priority between command-line patterns, directory ignore files, repository-local exclusions, and global exclusions. Within the same precedence level, the last matching pattern wins. A lower directory’s ignore file can override a parent’s rule for paths it governs. Pattern spelling and source location both matter.

Check it quickly

Run this Python script with Git available. It creates and removes a temporary repository, disables system and global Git configuration for its subprocesses, and uses invented fixture files. The recorded run used Git 2.50.1. No command operates on the repository from which you launch the script:

from pathlib import Path
from tempfile import TemporaryDirectory
import os,subprocess

env=dict(os.environ,GIT_CONFIG_NOSYSTEM='1',GIT_CONFIG_GLOBAL=os.devnull)
with TemporaryDirectory(prefix='git-ignore-lab-') as directory:
 root=Path(directory)
 def git(*args, expected=0):
 result=subprocess.run(['git',*args],cwd=root,env=env,text=True,capture_output=True)
 assert result.returncode==expected,(args,result.returncode,result.stderr)
 return result.stdout
 def write(path,content='fixture\n'):
 target=root/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 git('init','-q')
 git('config','user.name','Ignore Lab')
 git('config','user.email','ignore@example.invalid')
 git('config','commit.gpgsign','false')
 write('tracked.txt','first version\n')
 git('add','--','tracked.txt');git('commit','-qm','Track fixture')
 write('build/keep.txt');write('build/output.bin')
 write('.gitignore','/build/\n!/build/keep.txt\n')
 git('check-ignore','-q','build/keep.txt')
 print('excluded parent prevents child exception')
 write('.gitignore','/build/*\n!/build/keep.txt\n*.log\n/root-only.txt\ntracked.txt\n')
 git('check-ignore','-q','build/keep.txt',expected=1)
 rule=git('check-ignore','-v','build/keep.txt')
 assert ':2:!/build/keep.txt\t' in rule
 git('check-ignore','-q','build/output.bin')
 print('ignoring contents permits keep.txt; verbose output includes its negation')
 write('debug.log');write('nested/debug.log');write('nested/.gitignore','!debug.log\n')
 write('root-only.txt');write('nested/root-only.txt')
 git('check-ignore','-q','debug.log')
 git('check-ignore','-q','nested/debug.log',expected=1)
 git('check-ignore','-q','root-only.txt')
 git('check-ignore','-q','nested/root-only.txt',expected=1)
 print('nested exception and root anchor checked')
 write('tracked.txt','second version\n')
 git('add','-A')
 assert 'tracked.txt' in git('diff','--cached','--name-only').splitlines()
 git('check-ignore','-q','tracked.txt',expected=1)
 assert 'tracked.txt' in git('check-ignore','--no-index','-v','tracked.txt')
 git('rm','--cached','--','tracked.txt')
 assert (root/'tracked.txt').is_file()
 assert 'tracked.txt' not in git('ls-files').splitlines()
 git('cat-file','-e','HEAD:tracked.txt')
 print('tracked file still staged; cached removal keeps disk copy and old commit')
 git('add','-f','--','build/output.bin')
 assert 'build/output.bin' in git('ls-files').splitlines()
 print('force-add bypasses ignore rules')

The first check confirms that excluding build/ defeats the child exception. The revised rules exclude entries inside build instead, allowing keep.txt while still excluding output.bin. The quiet checks assert actual ignored status; exit one means the tested path is not ignored.

Verbose output for the allowed file still includes the matching negated rule. Therefore, seeing output from git check-ignore -v is not by itself proof that a path is excluded. Inspect the reported pattern, including its exclamation mark, and use the quiet result when you need a boolean decision. This distinction matters in scripts that turn diagnostic output into an automated gate.

The nested log exception overrides the root log rule within nested. The leading slash on /root-only.txt anchors it to the root ignore file’s directory, so the nested file remains eligible. These checks use actual created paths rather than guessing from a pattern’s visual shape.

The tracked file remains staged after its modification even though a new ignore pattern matches its name. --no-index asks the diagnostic command to consider that pattern without ordinary tracked-file exclusion. Removing the path with git rm --cached leaves its working copy on disk and removes it from the index, while the original committed blob remains accessible. Finally, force-add places an ignored build output into the index.

Review what the next commit will contain

Use shared .gitignore files for project-wide conventions, .git/info/exclude for exclusions local to one repository checkout, and a configured global excludes file for personal editor clutter. Do not make a team’s correct build depend on an undocumented global rule. Keep essential source inputs eligible even when neighboring generated output is excluded.

Before committing, inspect the staged diff and tracked paths, not just a clean-looking default status display. A broad pattern can hide a new source file; a forced addition can override an intended exclusion. Commit a change that stops tracking a local configuration file only with a replacement provisioning path, because other checkouts applying that deletion may remove their tracked copy.

For an actual credential exposure, revoke or replace the credential and investigate its distribution. Removing an index entry does not invalidate access already granted by that credential, and rewriting one repository cannot control existing copies elsewhere. Ignore rules prevent many routine mistakes, but staged-content review and appropriate secret detection provide additional checks with their own limits.

Sources

Git ignore rules, scope, precedence, and excluded-parent behavior, checked 2026-09-12.
git check-ignore, verbose negated patterns and index-aware diagnostics, checked 2026-09-12.
git rm, removing index entries while retaining working files, checked 2026-09-12.

git worktree checks out many branches at once

Sat, 06 Nov 2027 00:00:00 +0000

A hotfix need not displace unfinished feature work from its directory. A linked worktree can start from a chosen release commit while the original directory retains its staged changes, unstaged edits, and untracked files. The workflow succeeds when the fix is tested on the correct baseline and the original work remains intact. Merely creating a second folder does not establish either result.

Choose the baseline before opening another directory

Inspect the current worktree and identify the exact release revision needing the fix. A convenient branch name is not necessarily the deployed revision. If a remote-tracking reference must be refreshed, fetch the intended remote and then record the resolved commit. Fetching updates shared repository references; it does not modify only the directory where the command was entered.

Create the new worktree with an explicit path, branch name, and start point. Using a new hotfix branch avoids competing with a branch already checked out elsewhere. For inspection without intended commits, a detached worktree may be sufficient. Do not use branch-resetting or force options merely because the proposed name already exists; inspect the existing worktree and reference first.

Creation checks out committed content from the selected start point. It does not copy the original directory’s uncommitted feature changes or untracked notes. That separation is useful for reproducing a release problem without accidental fixes or dependencies from the feature workspace. It also means editor buffers and local configuration files do not automatically become available in the new directory.

Reproduce and verify in the actual hotfix tree

Confirm the new HEAD and run the targeted reproduction before changing code. After the repair, run that same check and the relevant broader tests against the hotfix directory. A passing command run from the feature directory is evidence about the wrong checkout. Keep test output associated with the exact commit, directory, and configuration used.

Build outputs placed inside each directory are separate files, but external state may still collide. Two servers can bind the same port, two test suites can write the same database, and shared caches may need correctly keyed entries. A worktree is not a container, virtual machine, or security boundary. Review what build commands execute and which resources they reach before running unfamiliar branch code.

Stage only the intended fix and inspect its diff before committing. The new commit is visible through the shared object database, but the original feature branch and its index need not move. Verify those unchanged states explicitly when preservation matters. Local availability also does not publish the branch or deploy the repair; distribution remains a separate authorized step.

When it breaks

The directory name can suggest a release while its HEAD actually points elsewhere. Check the resolved revision instead of trusting a folder label. Another common mistake is treating shared repository configuration as worktree-private configuration. A setting changed for a hotfix can affect other worktrees, even though their checked-out files remain untouched.

When finished, inspect the linked worktree’s status, untracked files, and valuable ignored outputs. Ordinary status omits ignored files; a clean tracked diff is not proof that the directory contains nothing worth saving. Keep required logs or artifacts outside the directory before removal. Stop processes still using it, because a clean Git status says nothing about running servers or open files.

Use normal git worktree remove on the confirmed path. It refuses ordinary dirty or untracked work rather than silently treating it as disposable. Investigate that refusal instead of routinely adding force. The command removes the linked checkout and its registration, not its branch. Prune is for stale administrative records whose directories are missing, not a command to delete active workspaces.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. The temporary repository excludes personal Git configuration and inherited Git routing, disables hooks and signing, and has no remote. The feature directory deliberately contains three kinds of unfinished work. The hotfix test first fails, then passes after a one-line repair.

import os
import subprocess
import sys
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-hotfix-demo-") as directory:
 root = Path(directory)
 feature, hotfix = root / "feature", root / "hotfix"
 feature.mkdir()
 def git(tree, *args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Hotfix Example",
 "-c", "user.email=hotfix@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=tree, env=env, text=True, capture_output=True, check=check,
 )
 def test():
 return subprocess.run([sys.executable, "-B", "-c",
 "from calc import double; assert double(4) == 8"],
 cwd=hotfix, text=True, capture_output=True)
 git(feature, "init", "-q", "-b", "feature")
 (feature / "calc.py").write_text("def double(n):\n return n * 2 + 1\n")
 (feature / "draft.txt").write_text("base\n")
 git(feature, "add", "calc.py", "draft.txt")
 git(feature, "commit", "-qm", "release baseline")
 baseline = git(feature, "rev-parse", "HEAD").stdout.strip()
 (feature / "draft.txt").write_text("staged\n")
 git(feature, "add", "draft.txt")
 (feature / "draft.txt").write_text("unstaged\n")
 (feature / "idea.txt").write_text("untracked idea\n")
 git(feature, "worktree", "add", "-qb", "hotfix", str(hotfix), baseline)
 print("clean-baseline:", git(hotfix, "rev-parse", "HEAD").stdout.strip() == baseline
 and (hotfix / "draft.txt").read_text() == "base\n"
 and not (hotfix / "idea.txt").exists())
 broken = test()
 print("regression-reproduced:", broken.returncode != 0 and "AssertionError" in broken.stderr)
 (hotfix / "calc.py").write_text("def double(n):\n return n * 2\n")
 fixed = test()
 assert fixed.returncode == 0 and not fixed.stderr, fixed
 git(hotfix, "add", "calc.py")
 git(hotfix, "commit", "-qm", "fix double")
 fixed_commit = git(hotfix, "rev-parse", "HEAD").stdout.strip()
 print("feature-preserved:", git(feature, "rev-parse", "HEAD").stdout.strip() == baseline
 and git(feature, "symbolic-ref", "--short", "HEAD").stdout.strip() == "feature"
 and git(feature, "show", ":draft.txt").stdout == "staged\n"
 and (feature / "draft.txt").read_text() == "unstaged\n"
 and (feature / "idea.txt").read_text() == "untracked idea\n")
 artifact = hotfix / "review-notes.txt"
 artifact.write_text("reviewed\n")
 refused = git(feature, "worktree", "remove", str(hotfix), check=False)
 print("dirty-removal-refused:", refused.returncode != 0 and artifact.exists())
 saved = root / "saved-review.txt"
 artifact.rename(saved)
 git(feature, "worktree", "remove", str(hotfix))
 print("checkout-removed-branch-kept:", not hotfix.exists()
 and git(feature, "rev-parse", "hotfix").stdout.strip() == fixed_commit)
 print("review-notes-preserved:", saved.read_text() == "reviewed\n")

All six observations should print True. The hotfix starts from committed baseline content, reproduces the bug, and leaves every original feature state unchanged. An untracked review note prevents removal until it is moved outside the linked checkout. Normal removal then succeeds while the hotfix branch and saved note remain. The outer temporary-directory cleanup intentionally discards all demonstration data only after these checks.

Sources

Git worktree reference, explicit creation, checkout safeguards, removal, and pruning, checked 2026-09-07.
Git status reference, staged versus working-tree changes and untracked or ignored files, checked 2026-09-07.

git bisect narrows the first bad commit

Sun, 24 Oct 2027 00:00:00 +0000

Bisection answers a precise historical question: within selected history, where does a reproducible observation change from good to bad? It does not identify a root cause merely by naming a commit. The search depends on correct endpoint labels and consistent intermediate decisions. Treat the reported boundary as evidence to inspect, then confirm the behavior on both sides and explain the change that accounts for it.

Choose endpoints by observation, not date

At least one known-good and one known-bad commit establish the search. More good revisions can further constrain a graph. A recently verified good commit usually reduces the range better than an unnecessarily ancient baseline. Dates are not the search order: Git uses ancestry, and a commit’s author timestamp need not describe where it sits in the graph.

Run the same reproduction at both endpoints before assigning labels. Define what counts as the symptom, including boundary inputs and relevant configuration. A test that simply checks whether any command fails can confuse the product regression with a missing interpreter, unavailable service, or incompatible build environment. An untestable revision has an unknown result, not an automatic bad verdict.

Use a clean disposable checkout or a dedicated worktree. Bisect normally changes HEAD to selected revisions and updates checked-out files. Preserve unfinished work beforehand without assuming that the search itself creates a backup. Keep the probe and required evidence outside files that disappear or change as historical revisions are checked out.

Make each decision about the same property

After inspecting the selected revision, record git bisect good or git bisect bad according to the reproduction. Use git bisect skip when a specific revision cannot be classified for a reason unrelated to the symptom. Skips near the transition may prevent a unique answer, so report the remaining candidate set instead of pretending the first displayed object is proven responsible.

Simple binary-search intuition assumes a reasonably stable transition in the selected history. A bug introduced, fixed, and later reintroduced is not a single monotonic timeline for that predicate. Nondeterministic tests create the same kind of misleading labels. Refine the question or the interval when the observations contradict the assumed transition; do not force them into a convenient story.

For a merge-heavy history, deciding whether to search all ancestry or only the first-parent integration line changes the question. A first-parent search can locate the merge where an integration branch acquired the failure rather than the original topic commit. Similarly, limiting paths can exclude a relevant configuration or caller change. Apply those restrictions only when they match the investigation.

When it breaks

One mistaken label can exclude the true boundary. Save git bisect log before abandoning the session. If a decision was wrong, retain the original evidence, correct the decision record, reset, and replay the corrected log. Replay reconstructs decisions; it does not rerun tests or prove their old environment is still valid.

When a candidate is found, rerun the exact reproduction there and on the relevant parent. For a normal linear boundary, the candidate should be bad and its parent good. A merge may require examining several parents and the combined behavior. Read the patch and affected call chain; a candidate that only exposes a preexisting issue still needs a causal explanation.

Avoid immediately reverting the candidate in a shared or dirty branch as a diagnostic shortcut. Any corrective experiment belongs in a controlled checkout with its own review and tests. After recording the findings, git bisect reset ends the session and normally restores the original checkout. Confirm the active branch and revision rather than assuming the final diagnostic checkout is the development branch.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. The temporary repository uses synthetic identity, disables hooks and signing, excludes personal Git configuration and routing variables, and has no remote. Seven revisions change a numerical limit from inclusive to exclusive at revision three. The probe checks the exact boundary input, ten.

import os
import subprocess
import sys
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-bisect-boundary-") as directory:
 root = Path(directory)
 repo, log = root / "repo", root / "bisect.log"
 repo.mkdir()
 def git(*args):
 return subprocess.run(
 ["git", "-c", "user.name=Boundary Example",
 "-c", "user.email=boundary@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=repo, env=env, text=True, capture_output=True, check=True,
 )
 def verdict():
 result = subprocess.run([sys.executable, "-B", "-c",
 "from limit import accepts; print(int(accepts(10)))"],
 cwd=repo, text=True, capture_output=True, check=True)
 assert result.stdout in ("0\n", "1\n"), result
 return "good" if result.stdout == "1\n" else "bad"
 git("init", "-q", "-b", "main")
 commits = []
 for number in range(7):
 operator = "<" if number >= 3 else "<="
 (repo / "limit.py").write_text(f"def accepts(n):\n return n {operator} 10\n")
 (repo / "revision.txt").write_text(f"{number}\n")
 git("add", "limit.py", "revision.txt")
 git("commit", "-qm", f"revision {number}")
 commits.append(git("rev-parse", "HEAD").stdout.strip())
 endpoints = []
 for revision in (commits[0], "main"):
 git("switch", "-q", "--detach", revision)
 endpoints.append(verdict())
 git("switch", "-q", "main")
 print("endpoints-confirmed:", endpoints == ["good", "bad"])
 git("bisect", "start", commits[-1], commits[0])
 try:
 while len(git("rev-list", "refs/bisect/bad", "--not",
 "--glob=refs/bisect/good-*").stdout.splitlines()) > 1:
 git("bisect", verdict())
 found = git("rev-parse", "refs/bisect/bad").stdout.strip()
 log.write_text(git("bisect", "log").stdout)
 print("boundary-identified:", found == commits[3])
 finally:
 git("bisect", "reset")
 checks = []
 for revision in (found, f"{found}^"):
 git("switch", "-q", "--detach", revision)
 checks.append(verdict())
 git("switch", "-q", "main")
 print("candidate-and-parent-retested:", checks == ["bad", "good"])
 try:
 git("bisect", "replay", str(log))
 print("log-replays-boundary:", git("rev-parse", "refs/bisect/bad").stdout.strip() == found)
 finally:
 git("bisect", "reset")
 print("original-branch-restored:", git("symbolic-ref", "--short", "HEAD").stdout.strip() == "main"
 and git("rev-parse", "HEAD").stdout.strip() == commits[-1]
 and not git("status", "--porcelain").stdout)

All five checks should print True. The loop uses explicit good/bad decisions until one candidate remains in this linear, skip-free fixture. Revision three is found, and independent retests show its boundary behavior fails while its parent succeeds. Replaying the saved log reaches the same result without repeating the probe, then reset restores main. The observed patch explains the regression: equality at the limit was removed.

Sources

Git bisect reference, labels, skips, ancestry restrictions, logging, and replay, checked 2026-09-07.
Pro Git: debugging with Git, testing historical endpoints and inspecting the discovered boundary, checked 2026-09-07.

A Compose project combines declarations with external inputs

Wed, 18 Aug 2027 00:00:00 +0000

Docker Compose turns service declarations into containers, networks, and storage attachments managed as a project. The file describes useful relationships: which image runs a service, how configuration reaches it, and which storage or network it uses. Reproducing a stack still depends on external inputs such as image availability, variable values, host capabilities, and existing data. A versioned file makes those inputs reviewable only when they are identified.

When it breaks

The same Compose text can resolve differently when the invoking shell supplies different variables. An env file participates in interpolation, but it is not automatically equivalent to the environment eventually injected into every container. Service-level environment declarations and env_file settings have their own roles. Inspect the rendered configuration and the running service rather than assuming a value in one file must be the final value.

Network addresses are another trap. Services on a Compose network can resolve one another by service name and use the container port. Published host ports serve a different path. Pointing a client container at localhost usually sends the request back to that client, not to the sibling API. Hardcoding a container IP also makes replacement more fragile than using the stable service name.

Project lifecycle does not give every resource the same lifetime. A normal down operation removes the project’s containers and networks, while named volumes remain unless volume removal is requested. Recreating the network can change its identity and assigned addresses. Retained data does not mean the old network survived, and a newly created container does not imply an empty data volume.

Check it quickly

Run the script with host Python, Docker Compose, and the pinned Python image. It was executed with Compose 5.1.1 and Docker 29.3.1 on Linux arm64. The generated Compose document uses JSON syntax accepted by YAML, requires no extra Python parser, and has a unique project name. The API is published only on host loopback at an automatically assigned port:

from pathlib import Path
from tempfile import TemporaryDirectory
from urllib.request import urlopen
import json,os,subprocess,time,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def run(args,check=True,env=None):
 result=subprocess.run(args,text=True,capture_output=True,timeout=120,env=env)
 if check:assert result.returncode==0,result.stderr
 return result
def docker(*args,check=True):return run(['docker',*args],check)

name='xbcatm-project-'+uuid.uuid4().hex[:10];environment=os.environ.copy();environment.pop('TASK_COMPOSE_GREETING',None)
with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);file=root/'compose.yaml'
 def compose(*args,check=True,env=None):return run(['docker','compose','-p',name,'--env-file',str(root/'.env'),'-f',str(file),*args],check,env or environment)
 def container(service):return compose('ps','-q',service).stdout.strip()
 def inspect(identity):return json.loads(docker('inspect',identity).stdout)[0]
 def request():
 port=inspect(container('api'))['NetworkSettings']['Ports']['8080/tcp'][0]
 assert port['HostIp']=='127.0.0.1'
 deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 try:
 with urlopen('http://127.0.0.1:'+port['HostPort'],timeout=1) as response:return response.read().decode()
 except OSError:time.sleep(.1)
 raise AssertionError('published endpoint unavailable')
 server='from http.server import BaseHTTPRequestHandler,HTTPServer\nimport os\nclass H(BaseHTTPRequestHandler):\n def do_GET(self):self.send_response(200);self.end_headers();self.wfile.write(os.environ["GREETING"].encode())\n def log_message(self,*args):pass\nHTTPServer(("0.0.0.0",8080),H).serve_forever()\n'
 spec={'services':{'api':{'image':BASE,'command':['python','-c',server],'environment':{'GREETING':'${TASK_COMPOSE_GREETING:-default}'},'ports':[{'target':8080,'published':'0','host_ip':'127.0.0.1'}],'volumes':['state:/state']},'client':{'image':BASE,'command':['python','-c','import time;time.sleep(180)']}},'volumes':{'state':{}}}
 file.write_text(json.dumps(spec,indent=2));(root/'.env').write_text('TASK_COMPOSE_GREETING=from-file\n')
 try:
 rendered=json.loads(compose('config','--format','json').stdout);assert rendered['services']['api']['environment']['GREETING']=='from-file'
 override=environment|{'TASK_COMPOSE_GREETING':'from-shell'}
 rendered=json.loads(compose('config','--format','json',env=override).stdout);assert rendered['services']['api']['environment']['GREETING']=='from-shell'
 compose('up','-d',env=override);assert request()=='from-shell'
 api=container('api');client=container('client');first_network=next(iter(inspect(api)['NetworkSettings']['Networks'].values()))['NetworkID']
 result=docker('exec',client,'python','-c','import urllib.request;print(urllib.request.urlopen("http://api:8080",timeout=2).read().decode())')
 assert result.stdout.strip()=='from-shell'
 docker('exec',client,'python','-c','import socket;s=socket.socket();assert s.connect_ex(("127.0.0.1",8080))!=0;s.close()')
 docker('exec',api,'python','-c','from pathlib import Path;Path("/state/record").write_text("preserved")')
 volume=next(m['Name'] for m in inspect(api)['Mounts'] if m['Destination']=='/state')
 assert volume==name+'_state'
 compose('down');assert docker('network','inspect',first_network,check=False).returncode!=0
 assert docker('volume','inspect',volume,check=False).returncode==0
 compose('up','-d',env=override);assert request()=='from-shell'
 api=container('api');assert next(iter(inspect(api)['NetworkSettings']['Networks'].values()))['NetworkID']!=first_network
 docker('exec',api,'python','-c','from pathlib import Path;assert Path("/state/record").read_text()=="preserved"')
 assert docker('exec',container('client'),'python','-c','import urllib.request;print(urllib.request.urlopen("http://api:8080",timeout=2).read().decode())').stdout.strip()=='from-shell'
 print('shell interpolation overrides .env; internal clients resolve api:8080 while localhost remains their own container')
 print('the host endpoint is published only on loopback; down/up recreates the project network and retains the named data volume')
 finally:compose('down','--volumes','--remove-orphans',check=False)

The private env file supplies TASK_COMPOSE_GREETING=from-file. The script explicitly selects that file and removes the same variable from its initial shell environment. compose config --format json resolves the service’s GREETING value to from-file. Providing from-shell in the invoking environment then changes the rendered value, establishing the tested interpolation precedence.

Starting the project with the override makes the API return from-shell. The host-side request uses the published port discovered through container inspection, and the binding is asserted to be 127.0.0.1. This verifies both the effective configuration and the intended exposure. Merely rendering a valid document would not prove the container was started with that value or port binding.

The client service successfully requests http://api:8080 through Compose’s network and gets the same response. A connection attempt to its own loopback port 8080 fails. These two observations distinguish service-name discovery from host publishing and container-local loopback. No fixed container IP is embedded in the application request.

The API writes a marker to its named state volume. After ordinary compose down, inspection confirms the old network no longer exists while the named volume still does. Bringing the project up again creates a different network identity. The marker remains readable, and the client can still reach the API using the unchanged service name.

The fixture’s final cleanup includes --volumes because all of its data is disposable. That option has a different destructive scope from the earlier ordinary down used to demonstrate retention. In a real environment, apply it only when removal of those volumes is intended; it should not be appended casually to every restart or troubleshooting command.

Record the project inputs that matter

Keep required variable names, image digests, storage ownership, and exposed ports explicit. Render configuration in the intended execution environment before starting the stack, but avoid publishing rendered output containing credentials. Pinning an image reduces one source of drift; it does not freeze host architecture, mounted files, runtime configuration, or persistent database contents.

Use separate project names for independent local or CI runs when resources should be isolated. Explicitly named external networks or volumes can intentionally cross that boundary, so review those references rather than assuming project naming isolates every attachment. Port bindings can also conflict across otherwise separate projects.

Compose can support a managed single-host deployment as well as local testing. Its suitability depends on operational requirements, not a blanket ban on production use. Host redundancy, rollout coordination, backup, readiness, and monitoring still need deliberate solutions. The value of the declaration is a clear, testable resource model with known limits.

Sources

Compose services reference, service configuration, environment, ports, and volume mounts, checked 2026-09-12.
Networking in Compose, project networks and service-name discovery, checked 2026-09-12.
Compose variable interpolation, shell and env-file interpolation precedence, checked 2026-09-12.
Docker compose down, network removal and optional volume removal, checked 2026-09-12.

Small commits tell a coherent story

Sun, 25 Jul 2027 00:00:00 +0000

A useful commit answers one question about the behavior of a repository. It includes the implementation, the checks that establish that behavior, and documentation needed to use it. Smallness means a bounded reason for change, rather than a target number of lines. An inclusive shipping threshold might require edits to both a function and its regression test while leaving an unrelated draft outside the commit.

The index defines the checkpoint

Git distinguishes the working tree, the index, and the committed tree. Editing a file changes the working tree. Adding it copies its current content into the index. Further edits do not automatically update that staged version. A successful test against the working tree can therefore exercise code that the proposed commit does not contain. Inspect the staged diff, including deletions and new files, and test the selected snapshot when partial staging creates meaningful differences.

The index is particularly useful when two independent tasks share a checkout. Stage only the paths or hunks belonging to the current purpose. Before committing, check that required imports, fixtures, configuration, and tests are included. A tiny implementation patch without its required schema change is not an independently usable checkpoint. Conversely, a mechanical rename across many files can still express one coherent operation.

When it breaks

A mixed commit couples unrelated decisions. Reverting a visual change might remove a reliability fix hidden beside it. Splitting the files arbitrarily does not solve this when the first commit calls an API introduced only by the second. Aim for meaningful intermediate states, and state dependencies explicitly when a sequence must be reviewed together.

Small commits improve the information available to a reviewer; they do not guarantee conflict-free or operationally safe reversal. Later code may depend on an earlier behavior, and a completed database migration may have effects outside Git. A revert records a new inverse change and can conflict with intervening edits. Review and test the resulting state before deploying it.

Bisect also needs a reliable good-or-bad test at historical revisions. An uncompilable midpoint is not automatically evidence that the regression began there. Skipping untestable commits may leave several possible candidates. Keeping checkpoints executable makes the search more useful, but neither commit size nor a descriptive subject can repair a flaky test.

Check it quickly

Save the following as small-commits.py and run python3 small-commits.py with Git installed. It creates a temporary repository, uses an isolated Git configuration and empty hooks directory, and makes two local commits there. The application charges five units below a subtotal of fifty and should charge zero at fifty. The initial implementation incorrectly includes fifty in the charged range.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess
import sys

with TemporaryDirectory() as directory:
 repo = Path(directory) / 'repo'
 repo.mkdir()
 hooks = Path(directory) / 'empty-hooks'
 hooks.mkdir()
 env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C',
 'GIT_CONFIG_NOSYSTEM': '1', 'GIT_CONFIG_GLOBAL': os.devnull}

 def git(*args):
 return subprocess.check_output([
 'git', '-c', 'user.name=Example', '-c', 'user.email=example@example.invalid',
 '-c', 'commit.gpgsign=false', '-c', f'core.hooksPath={hooks}',
 '-c', 'core.autocrlf=false', *args], cwd=repo, env=env, text=True)

 git('init', '-q', '-b', 'main')
 (repo / 'price.py').write_text('def shipping(subtotal):\n return 5 if subtotal <= 50 else 0\n')
 (repo / 'test_price.py').write_text('from price import shipping\nassert shipping(49) == 5\n')
 (repo / 'notes.txt').write_text('unrelated draft\n')
 git('add', 'price.py', 'test_price.py', 'notes.txt')
 git('commit', '-qm', 'Add shipping calculation and its initial check')
 test = 'from price import shipping\nassert shipping(49) == 5\nassert shipping(50) == 0\n'
 (repo / 'test_price.py').write_text(test)
 failed = subprocess.run([sys.executable, '-B', 'test_price.py'], cwd=repo,
 capture_output=True, text=True)
 assert failed.returncode != 0 and 'AssertionError' in failed.stderr
 (repo / 'price.py').write_text('def shipping(subtotal):\n return 5 if subtotal < 50 else 0\n')
 (repo / 'notes.txt').write_text('unrelated draft, still being edited\n')
 git('add', 'price.py', 'test_price.py')
 staged = git('diff', '--cached', '--name-only').splitlines()
 assert staged == ['price.py', 'test_price.py']
 snapshot = Path(directory) / 'index-snapshot'
 snapshot.mkdir()
 for name in staged:
 (snapshot / name).write_text(git('show', ':' + name))
 subprocess.run([sys.executable, '-B', 'test_price.py'], cwd=snapshot, check=True)
 git('commit', '-qm', 'Make the free-shipping threshold inclusive')
 assert git('status', '--porcelain') == ' M notes.txt\n'
 assert git('show', 'HEAD:notes.txt') == 'unrelated draft\n'
 print(json.dumps({'regression_failed_before_fix': True,
 'staged_files': staged, 'staged_test_passed': True,
 'unrelated_edit_preserved': True}))

The new boundary assertion first fails against the old function. After the fix, only price.py and test_price.py enter the index. The script copies their staged bytes into a separate directory and runs the assertion there before committing. The JSON result reports both the earlier failure and the passing staged test.

The final status contains only the unrelated modification to notes.txt; its committed version still has the original text. That verifies selective staging without discarding another task’s work. The fixture tests one complete pair of files, not every possible partial-staging arrangement, and it does not perform a revert or a bisect session.

Write the reason that survives the diff

A subject such as “Make the free-shipping threshold inclusive” identifies the changed behavior. Explain the observed boundary error, the intended contract, and the relevant validation in the body when those details are not obvious. Avoid claiming that a test passed merely because a test file was added. Record which snapshot actually ran. Before publishing a sequence, read its combined diff and its individual checkpoints: the complete feature must work, and the intermediate story should accurately describe how it becomes usable.

Sources

Git: git-add, how the index records selected content, checked 2026-09-13.
Git: git-bisect, testable revisions and skipped commits, checked 2026-09-13.
Git: git-revert, reversal commits and conflicts, checked 2026-09-13.

Docs as code make claims reviewable

Mon, 29 Mar 2027 00:00:00 +0000

A guide can be stored beside the application and still describe a command that never worked. Docs as code provides a way to discover and review that mistake: plain source files, version history, ownership, a preview, and checks attached to the change. It does not make prose correct automatically. The valuable link is between a documented claim and evidence from the implementation that the reader will actually use.

Version the reader’s contract

Document the behavior of a specific release. A command copied from the development branch may require an option missing from the installed package. Keep version selection visible, and update the implementation and the affected instructions in the same review when practical. Reviewers should inspect changed defaults, required privileges, input files, expected output, and any cleanup a procedure requires. A successful page build checks only part of that contract.

Keep a single authoritative source for mechanical facts where the project already has one. An option table generated from a schema can reduce duplicate maintenance, but its generator may omit defaults, misinterpret types, or describe flags unavailable in the packaged executable. Review generator changes and compare useful examples with the built program. Generated reference material and a human explanation serve different purposes; neither guarantees the other’s accuracy.

When it breaks

An example copied into a separate test can pass while the displayed command drifts. Execute the example extracted from the document where the format permits it, or generate both from a shared tested input. Avoid teaching an undocumented abbreviation: a parser that currently accepts a shortened option may accept it only until another option makes that prefix ambiguous.

Working directories also matter. A guide can depend on a file already present on the author’s machine, a cached dependency, or an inherited credential. A clean fixture should create its own harmless inputs and state its prerequisites. Do not execute arbitrary contributed shell snippets with release credentials merely because they live in Markdown. Give documentation checks the permissions their examples require.

Links, spelling, and formatting are useful checks, but they cannot determine whether the procedure solves the reader’s problem. A real command can exit successfully while producing output in the wrong order or modifying the wrong file. Inspect the meaningful result, and keep a human review of assumptions, failure recovery, and the audience’s starting point.

Check it quickly

Save this code as docs-code.py and run python3 docs-code.py. It uses Python’s standard library and a temporary directory. The fixture creates a JSON input with keys in the order z, then a, and a short Markdown guide. Its initial fenced command claims that json.tool supports --sort-fields, which is intentionally incorrect.

from pathlib import Path
from tempfile import TemporaryDirectory
import difflib
import json
import re
import shlex
import subprocess
import sys

with TemporaryDirectory() as directory:
 root = Path(directory)
 (root / 'sample.json').write_text('{"z":2,"a":1}\n')
 doc = root / 'guide.md'
 old = '# Format JSON\n\n```sh\npython3 -m json.tool --sort-fields sample.json\n```\n'
 doc.write_text(old)

 def execute_document():
 command = re.search(r'```sh\n([^\n]+)\n```', doc.read_text())[1]
 args = shlex.split(command)
 assert args[:3] == ['python3', '-m', 'json.tool']
 return subprocess.run([sys.executable, *args[1:]], cwd=root,
 capture_output=True, text=True)

 failed = execute_document()
 assert failed.returncode == 2 and 'unrecognized arguments' in failed.stderr
 doc.write_text(old.replace('--sort-fields', '--sort-keys'))
 passed = execute_document()
 assert passed.returncode == 0
 assert list(json.loads(passed.stdout)) == ['a', 'z']
 delta = ''.join(difflib.unified_diff(old.splitlines(True), doc.read_text().splitlines(True),
 fromfile='before/guide.md', tofile='after/guide.md'))
 print(json.dumps({'broken_command_exit': failed.returncode,
 'corrected_command_exit': passed.returncode,
 'parsed_keys': list(json.loads(passed.stdout)), 'doc_diff': delta}))

The script extracts the displayed command, splits its arguments without a shell, and runs the current interpreter’s real JSON tool. The first invocation must exit with status two and report an unrecognized argument. The guide is then corrected to --sort-keys. The second invocation must succeed, and the parsed output must contain keys in the order a, then z.

The final JSON includes the documentation diff as well as both statuses. This verifies the exact example and its relevant result instead of treating an added test as evidence. The extractor deliberately handles one known, single-line command and checks its prefix; it is not a general Markdown execution engine. It does not establish that unrelated pages, links, or release packages have been checked.

Make publication traceable

Publish the rendered documentation from the reviewed revision and record which application release it describes. Check the preview for code wrapping, navigation, and language selection, because correct source can still become an unusable page. When a check fails, decide whether the implementation, the example, or the documented contract is wrong before changing either. The reviewable diff helps people make that decision; the repository itself does not enforce agreement between prose and behavior.

Sources

Write the Docs: Docs as Code, version control, review, and executable checks for documentation, checked 2026-09-13.
Python 3.14: json, the real json.tool command and sort-keys option, checked 2026-09-13.

Workflow · XB Field Notes

git stash saves work for later

Know what the snapshot includes

Applying is different from popping

When it breaks

Check it quickly

Sources

git cherry-pick re-applies a commit

Select a change relative to its parent

A backport needs dependency review

When it breaks

Check it quickly

Sources

.gitignore controls untracked paths

When it breaks

Check it quickly

Review what the next commit will contain

Sources

git worktree checks out many branches at once

Choose the baseline before opening another directory

Reproduce and verify in the actual hotfix tree

When it breaks

Check it quickly

Sources

git bisect narrows the first bad commit

Choose endpoints by observation, not date

Make each decision about the same property

When it breaks

Check it quickly

Further reading

Sources

A Compose project combines declarations with external inputs

When it breaks

Check it quickly

Record the project inputs that matter

Sources

Small commits tell a coherent story

The index defines the checkpoint

When it breaks

Check it quickly

Write the reason that survives the diff

Sources

Docs as code make claims reviewable

Version the reader’s contract

When it breaks

Check it quickly

Make publication traceable

Further reading

Sources