Git · XB Field Notes

Merge and rebase draw different history lines

Tue, 18 Jan 2028 00:00:00 +0000

Merge and rebase integrate work with different consequences for commit identity and ancestry. A merge normally retains the existing commits and joins their histories; a rebase transplants selected changes onto another base. The choice is not only how a graph looks. It affects review references, conflict handling, signatures, and collaborators who already depend on the old commits. Decide using the repository’s workflow and the actual branch relationships.

What a merge records

When two tips have diverged, an ordinary two-branch merge creates a commit with both tips as parents and a resulting tree. Existing commits keep their identities. The graph preserves their ancestry, not a total chronological ordering of every activity. Commit dates and display order are not substitutes for parent relationships.

If the current tip is an ancestor of the incoming tip, the merge may instead fast-forward the branch without creating a merge commit. Requiring a merge commit is a separate policy expressed by options such as --no-ff. Conversely, keeping both parents does not guarantee that the result retains both branches’ intended behavior. Content review and integration tests remain necessary.

What a rebase changes

An ordinary rebase identifies the selected commits and reapplies their changes on the new base. A recreated commit with a different parent has a different object ID, even if its patch looks the same. Original author information is normally retained, but the new commit object needs its own verification and any required signature. Links to old commit IDs do not automatically become links to the new ones.

Not every rebase rewrites every commit: an already current branch can require no replay, and equivalent upstream changes or empty results can affect which commits remain. Standard rebasing linearizes the selected work by omitting merge commits from the replay. The explicit --rebase-merges mode attempts to recreate branching structure, so “rebase always produces a straight line” is also too broad.

A merge reconciles branch tips, whereas rebase usually processes individual commits in sequence. Conflict locations and frequency can therefore differ, and a resolution may be needed more than once. Compare the final tree and the replayed changes, then rerun relevant tests; similar-looking patches do not establish identical behavior on a changed base.

When it breaks

Rewriting commits that other work depends on creates coordination costs. A private unpublished branch is usually simpler to rebase than a shared integration branch. An explicitly agreed shared-history rewrite is possible, but requires identifying affected references and consumers. A general preference for linear history is not authorization to replace someone else’s published work.

Rebase does not inherently require a forced push. A new remote branch can be created normally, and a remote tip that remains an ancestor can accept a fast-forward. Replacing a remote tip whose commits were rewritten is the non-fast-forward case. Even a lease is only a concurrency check against an expected remote value, not approval for the replacement or proof that all collaborators have been considered.

During a rebase conflict, the merge backend’s “ours” side is the rebased history so far, including the upstream base; “theirs” is the commit being replayed. Those labels can surprise someone thinking only in terms of their original feature branch. Inspect the actual versions and intended contract before resolving. Stage the specific files and continue; skipping discards the current patch rather than fixing it.

If the operation should be abandoned, git rebase --abort restores its original branch state. Starting clean makes that recovery easier to reason about. Do not treat abort as a general backup for unrelated edits made during the operation, or use forceful cleanup as routine conflict handling.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. It uses a temporary repository, example identity, disabled hooks and signing, and no remote. Inherited Git routing and personal configuration are excluded. Two branches start from the same topic commit and integrate one independent upstream change using different operations.

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-merge-rebase-") as directory:
 root = Path(directory)
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=History Example",
 "-c", "user.email=history@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")
 git("commit", "--allow-empty", "-qm", "base")
 git("switch", "-qc", "topic")
 (root / "topic.txt").write_text("feature\n")
 git("add", "topic.txt")
 git("commit", "-qm", "feature")
 original = git("rev-parse", "HEAD").stdout.strip()
 git("branch", "merge-case")
 git("branch", "rebase-case")
 git("switch", "-q", "main")
 (root / "main.txt").write_text("upstream\n")
 git("add", "main.txt")
 git("commit", "-qm", "upstream")
 upstream = git("rev-parse", "HEAD").stdout.strip()
 git("switch", "-q", "merge-case")
 git("merge", "--no-edit", "main")
 merged = git("rev-parse", "HEAD").stdout.strip()
 print("merge-keeps-two-parents:", git("rev-parse", "HEAD^1").stdout.strip() == original
 and git("rev-parse", "HEAD^2").stdout.strip() == upstream)
 git("switch", "-q", "rebase-case")
 git("rebase", "main")
 rebased = git("rev-parse", "HEAD").stdout.strip()
 print("rebase-changes-commit:", rebased != original
 and git("rev-parse", "HEAD^").stdout.strip() == upstream)
 print("same-result-tree:", git("rev-parse", f"{merged}^{{tree}}").stdout
 == git("rev-parse", f"{rebased}^{{tree}}").stdout)
 print("original-topic-retained:", git("rev-parse", "topic").stdout.strip() == original
 and git("merge-base", "--is-ancestor", original, rebased, check=False).returncode == 1)
 git("switch", "-qc", "conflict", "topic")
 (root / "main.txt").write_text("topic alternative\n")
 git("add", "main.txt")
 git("commit", "-qm", "alternative upstream file")
 before = git("rev-parse", "HEAD").stdout.strip()
 stopped = git("rebase", "main", check=False)
 print("rebase-conflict-stops:", stopped.returncode != 0 and bool(git("ls-files", "-u").stdout))
 git("rebase", "--abort")
 print("abort-restores-branch:", git("rev-parse", "HEAD").stdout.strip() == before
 and git("symbolic-ref", "--short", "HEAD").stdout.strip() == "conflict"
 and (root / "main.txt").read_text() == "topic alternative\n"
 and not git("status", "--porcelain").stdout)

All six checks should print True. The merge has two expected parents; the rebase creates a new topic commit on the upstream tip. Their result trees match in this deliberately nonconflicting fixture, while the original topic commit remains named separately. A later add/add conflict stops rebase, and abort restores that branch’s exact tip, file contents, and clean status. No remote update is exercised or implied.

Sources

Git rebase reference, replay selection, merge recreation, conflict sides, and abort behavior, checked 2026-09-07.
Git merge reference, parent relationships, fast-forwards, and resulting trees, checked 2026-09-07.

Git merge joins two diverged lines at a new commit

Wed, 29 Dec 2027 00:00:00 +0000

A merge connects histories and records a resulting project snapshot. In an ordinary merge of two diverged branches, the new commit names both prior tips as parents. Those parent links keep the earlier commits reachable, but they do not prove that the resulting files retain every intended behavior. Merging is both a graph operation and a content decision; verifying only one of those aspects leaves important mistakes undetected.

Parents preserve history, not a single timeline

If the current tip is an ancestor of the incoming tip, a fast-forward can simply move the current branch reference. No extra merge commit is needed. Once both sides have their own commits, the normal merge instead creates a result with two parents: the previous current tip first and the incoming tip second. The graph still contains both lines; it has not rewritten them into one linear sequence.

Git reconciles the tips using their merge base, or merge bases in more complicated history. Comparing each side against shared ancestry distinguishes changes from unchanged context. A clean textual result means the merge machinery found a way to combine the files under the selected strategy. It does not mean Git understood the application’s interfaces, business rules, or deployment dependencies.

Review the tree before recording the join

Start with a known, preserved working state. Uncommitted modifications can prevent merging and can complicate reconstructing the original state after failure. Do not assume an abort will recover arbitrary edits made before or during an operation. Record the actual branch tips being joined so review and subsequent checks refer to stable objects rather than moving names.

For an explicitly reviewed merge commit, --no-commit pauses before recording the result. It cannot stop a fast-forward, so combine it with --no-ff when the intended workflow requires a merge commit even for a linear case. Inspect the staged changes, compare the candidate result with both parents, and run the tests affected by either side. The example uses this pause to catch and repair a behavioral incompatibility before committing.

When it breaks

A textual conflict is not limited to two edits on the same line. Deletes, renames, binary changes, and other incompatible operations can require a decision. Use git status and unmerged index entries to identify unresolved paths. For ordinary text conflicts, markers help inspect the alternatives; their absence alone does not prove every conflict was resolved.

Resolve according to the contract of the combined program, then stage the specific paths and continue or commit. Removing markers and running git add only tells Git that a resolution was supplied. Generated files should be regenerated from reconciled authoritative inputs, not merged independently into a plausible-looking output that the next build will overwrite.

A more subtle failure is a clean merge with broken behavior. One branch can tighten a function’s accepted arguments while another introduces a caller using the old form. They touch different files and can each pass their own checks, yet the combined program fails. Integration tests must exercise relationships introduced by the combination, not merely repeat two isolated branch summaries.

Strategy choices can also deliberately discard content. -Xtheirs favors incoming conflicting hunks while retaining other nonconflicting changes; it is not a universal instruction to preserve both intentions. The distinct ours strategy keeps the current tree while still recording the other history as merged. A two-parent graph therefore cannot prove that the incoming implementation was adopted. Such choices require an explicit reason and content review.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. Everything happens in a temporary repository with example identity, no remote, disabled hooks and signing, and no inherited Git routing or personal configuration. One branch changes a Python API to require a keyword argument; the other adds a positional caller. Python’s bytecode writing is disabled to keep the working tree clean.

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-merge-demo-") as directory:
 root = Path(directory)
 def git(*args):
 return subprocess.run(
 ["git", "-c", "user.name=Merge Example",
 "-c", "user.email=merge@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=root, env=env, text=True, capture_output=True, check=True,
 )
 def python(*args):
 return subprocess.run([sys.executable, "-B", *args], cwd=root,
 text=True, capture_output=True)
 git("init", "-q", "-b", "main")
 (root / "api.py").write_text('def render(name):\n return "Hi " + name\n')
 git("add", "api.py")
 git("commit", "-qm", "base API")
 git("switch", "-qc", "topic")
 (root / "api.py").write_text('def render(*, name):\n return "Hi " + name\n')
 git("add", "api.py")
 git("commit", "-qm", "require a named argument")
 topic = git("rev-parse", "HEAD").stdout.strip()
 topic_test = python("-c", 'from api import render; print(render(name="Ada"))')
 print("topic-test-passed:", topic_test.returncode == 0 and topic_test.stdout == "Hi Ada\n")
 git("switch", "-q", "main")
 (root / "client.py").write_text('from api import render\nprint(render("Ada"))\n')
 git("add", "client.py")
 git("commit", "-qm", "add a caller")
 main = git("rev-parse", "HEAD").stdout.strip()
 main_test = python("client.py")
 print("main-test-passed:", main_test.returncode == 0 and main_test.stdout == "Hi Ada\n")
 git("merge", "--no-ff", "--no-commit", "topic")
 print("text-merge-clean:", not git("ls-files", "-u").stdout
 and git("rev-parse", "MERGE_HEAD").stdout.strip() == topic)
 broken = python("client.py")
 print("combined-behavior-failed:", broken.returncode != 0 and "TypeError" in broken.stderr)
 (root / "client.py").write_text('from api import render\nprint(render(name="Ada"))\n')
 fixed = python("client.py")
 assert fixed.returncode == 0 and fixed.stdout == "Hi Ada\n", fixed
 git("add", "client.py")
 git("commit", "-qm", "merge topic and adapt the caller")
 print("reviewed-merge-parents:", git("rev-parse", "HEAD^1").stdout.strip() == main
 and git("rev-parse", "HEAD^2").stdout.strip() == topic)
 print("fixed-and-clean:", not git("status", "--porcelain").stdout)

All six observations should be True. Both branch checks pass separately, and Git reports no unmerged paths, but the combined caller raises TypeError. Adapting the caller restores the intended output before the merge is recorded. The final commit has the two expected parents and a clean worktree. This verifies a real clean-merge failure and its repair, while showing why preserved ancestry is not evidence of preserved behavior.

Sources

Git merge reference, merge states, parents, review controls, and strategy semantics, checked 2026-09-07.
Pro Git: basic branching and merging, fast-forwards, three-way merges, and unresolved paths, checked 2026-09-07.

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 git worktree checks out two branches at once

Mon, 26 Jul 2027 00:00:00 +0000

A linked worktree gives one Git repository another working directory, with its own checked-out state. That lets a feature, release, or review stay open alongside other work without repeatedly replacing the same files. The useful boundary is separate working files and staging, not complete isolation. Objects, many references, and ordinary repository configuration are shared, so operations need to respect both the local workspace and the common repository.

Identify the state that belongs to each checkout

Each worktree has its own HEAD and index. A staged change in one directory does not appear in the other’s index, and editing a tracked file does not edit its counterpart next door. Committing in a linked worktree normally advances its selected branch. That new object and shared branch reference are immediately available to Git commands run from the other worktrees, without a fetch between them.

The linked directory’s .git entry is normally a file pointing to its administrative directory. The checked-out source files live at the path chosen for the worktree, not inside the administrative .git/worktrees entry. Tools that assume .git must be a directory can fail here. Ask Git for --git-common-dir, --absolute-git-dir, or --git-path index instead of constructing internal paths yourself.

Objects are shared, but working files and build outputs still consume space separately. A second checkout is not another complete object database, yet it is not a zero-copy view of every source and generated file. Estimate disk use from the actual checkout and build requirements, especially when several release versions remain open.

Shared does not mean every item is shared

Local branches and tags generally belong to the common repository. HEAD and operation-specific state belong to a worktree; some references, including those under refs/bisect, are also per-worktree. Treating every reference as either globally shared or entirely local produces incorrect tooling. Use Git commands to resolve the relevant reference in the intended worktree.

Repository configuration is shared by default. A git config --local change made while standing in the review directory can therefore affect the feature directory too. Git supports explicitly enabled worktree-specific configuration, but enabling that extension is a repository configuration change requiring its documented migration rules. Do not silently assume ordinary local configuration already means local to this checkout.

Likewise, a shared stash list is not a private scratch area for one worktree. Name and inspect any saved work before applying or dropping it. Separate source directories also do not automatically isolate network ports, databases, external caches, or credentials used by commands launched from them.

When it breaks

By default, Git refuses to check out the same local branch in two worktrees. This protects separate indexes and files from competing updates to one moving reference. It is a safeguard that force options can override, not an unbreakable storage law. Prefer a distinct branch for independent changes or a detached checkout for inspecting the same commit, instead of bypassing the guard as routine setup.

A detached checkout has no local branch advancing with new commits. If its experimental work must survive removal, give the desired commit a branch name first. Removing a worktree does not automatically delete its branch, and pruning stale administration is not the same as deleting a live checkout. Use the operation that matches the actual state.

For moves, prefer git worktree move where supported; use repair to reconnect a manually moved checkout. A temporarily unavailable removable volume is not necessarily abandoned. Locking that worktree can prevent its registration from being pruned while it is offline. Avoid manually editing administrative files as a general recovery recipe.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. The temporary repository excludes inherited Git routing and personal configuration, uses example identity, and disables hooks and signing. The only configuration written is a synthetic demonstration key. Two tracked versions are staged independently, then a linked commit becomes visible from the main directory.

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-worktree-state-") as directory:
 root = Path(directory)
 main, review, detached = root / "main", root / "review", root / "detached"
 main.mkdir()
 def git(tree, *args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Worktree Example",
 "-c", "user.email=worktree@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=tree, env=env, text=True, capture_output=True, check=check,
 )
 git(main, "init", "-q", "-b", "main")
 (main / "note.txt").write_text("base\n")
 git(main, "add", "note.txt")
 git(main, "commit", "-qm", "base")
 git(main, "worktree", "add", "-qb", "review", str(review), "HEAD")
 common = [(tree / git(tree, "rev-parse", "--git-common-dir").stdout.strip()).resolve()
 for tree in (main, review)]
 indexes = [(tree / git(tree, "rev-parse", "--git-path", "index").stdout.strip()).resolve()
 for tree in (main, review)]
 print("shared-common-dir:", common[0] == common[1])
 print("separate-indexes:", indexes[0] != indexes[1])
 (main / "note.txt").write_text("main staged\n")
 git(main, "add", "note.txt")
 (review / "note.txt").write_text("review staged\n")
 git(review, "add", "note.txt")
 print("independent-staging:", git(main, "show", ":note.txt").stdout == "main staged\n"
 and git(review, "show", ":note.txt").stdout == "review staged\n")
 git(main, "config", "--local", "demo.shared", "visible")
 print("shared-local-config:", git(review, "config", "--get", "demo.shared").stdout.strip() == "visible")
 git(review, "commit", "-qm", "review change")
 print("commit-visible-from-main:", git(main, "show", "review:note.txt").stdout == "review staged\n")
 print("main-staging-unchanged:", git(main, "show", ":note.txt").stdout == "main staged\n"
 and (main / "note.txt").read_text() == "main staged\n")
 duplicate = git(main, "worktree", "add", str(root / "duplicate"), "main", check=False)
 print("duplicate-branch-refused:", duplicate.returncode != 0)
 git(main, "worktree", "add", "-q", "--detach", str(detached), "main")
 print("detached-copy-allowed:", git(detached, "symbolic-ref", "-q", "HEAD", check=False).returncode == 1)
 git(main, "worktree", "remove", str(review))
 git(main, "worktree", "remove", str(detached))

All eight checks should print True. The administrative paths establish a common repository and separate indexes. Each index retains its own staged text, while the synthetic configuration and committed review branch are shared. A duplicate attached branch is rejected, but a detached checkout of the same commit is allowed. The experiment removes only its clean linked checkouts; Python then cleans the disposable main directory.

Sources

Git worktree reference, shared state, per-worktree state, safeguards, and lifecycle commands, checked 2026-09-07.
Git repository layout, linked administrative directories, common storage, and index placement, checked 2026-09-07.

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.

git bisect automates a regression search

Wed, 07 Jul 2027 00:00:00 +0000

Automated bisection repeatedly checks a revision and turns the result into a history decision. It can replace many manual checkouts with roughly logarithmic probes on a simple range, but the speedup depends on a trustworthy test. A wrapper that misclassifies missing tools or broken infrastructure can confidently identify the wrong commit. Designing the verdict contract is therefore part of debugging, not merely setup around the search.

Establish a reproducible question

Choose one observable regression and verify it on the proposed good and bad endpoints using the same runner. A release name believed to be healthy is weaker evidence than a successful reproduction check. Keep inputs, toolchain, dependencies, and relevant environment consistent enough that the source revision is the variable under investigation.

Start with the bad revision followed by the known good revision. Git selects intermediate commits and invokes the runner from the checked-out worktree. Keep the runner at a stable path outside the history being changed, or otherwise ensure every tested revision contains a usable version. A relative script that disappears halfway through the search is an infrastructure failure, not evidence that the product became bad.

Map results to bisect’s actual contract

For git bisect run, zero means good. Codes one through 127 mean bad, except 125, which means the revision cannot be tested and should be skipped. Other status values abort the automated search. This is not equivalent to the usual summary that every nonzero code means a regression.

The documented bad range includes 126 and 127, commonly associated with an unexecutable or missing command. Preflight required tools and translate recognized infrastructure failures into an abort status, such as 200. Do not pass through a test tool’s every nonzero result without checking what it means. Likewise, a shell exit value outside the representable range can be truncated; choose a deliberate supported code.

Skipping is appropriate for a specific untestable revision whose classification is unknown, not for every failed build. If the regression being searched is itself a build failure, skipping that outcome would discard the evidence. Conversely, an obsolete dependency unrelated to the symptom must not automatically label an old commit bad. Record why the wrapper distinguishes those cases.

When it breaks

An output pipeline can lose the test’s status when its final logging command succeeds. A cleanup command can overwrite it for the same reason. Save the test result before recording diagnostics, and explicitly exit with the intended mapped verdict. Producing an error message on standard error does not stop Git from accepting an accidental zero.

Tests that change source files, reuse stale build output, or depend on mutable remote services can make successive revisions incomparable. Isolate generated files and retain enough logs to explain each decision. Do not clean a broad user workspace just to make a runner repeatable; use a disposable test environment whose owned paths are explicit.

Skips near the transition can leave several possible first-bad commits. A flaky or nonmonotonic predicate can also invalidate the simple boundary assumption. More probes cannot repair incorrect labels. Inspect the search log and retest the reported boundary and its relevant parent before attributing the root cause. Commit graphs, skipped revisions, and variable build costs also mean logarithmic probe counts are not a wall-clock guarantee.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. The isolated temporary repository excludes personal Git configuration and routing variables, disables hooks and signing, and has no remote. Nine synthetic revisions encode good, bad, or untestable fixture states. The first bad fixture is revision seven, while revision four exercises the skip path.

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-run-") as directory:
 root = Path(directory)
 repo, probe = root / "repo", root / "probe.py"
 repo.mkdir()
 probe.write_text('''from pathlib import Path
import sys
try:
 state = Path("state.txt").read_text().strip()
except OSError:
 sys.exit(200)
code = {"good": 0, "bad": 1, "skip": 125}.get(state, 200)
print(f"probe={state} code={code}")
sys.exit(code)
''')
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Bisect Example",
 "-c", "user.email=bisect@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=repo, env=env, text=True, capture_output=True, check=check,
 )
 git("init", "-q", "-b", "main")
 commits = []
 for number in range(9):
 state = "skip" if number == 4 else ("bad" if number >= 7 else "good")
 (repo / "state.txt").write_text(state + "\n")
 git("add", "state.txt")
 git("commit", "--allow-empty", "-qm", f"revision {number}")
 commits.append(git("rev-parse", "HEAD").stdout.strip())
 codes = []
 for revision in (commits[0], "main"):
 git("switch", "-q", "--detach", revision)
 codes.append(subprocess.run([sys.executable, str(probe)], cwd=repo,
 text=True, capture_output=True).returncode)
 git("switch", "-q", "main")
 print("endpoints-verified:", codes == [0, 1])
 git("bisect", "start", commits[-1], commits[0])
 try:
 run = git("bisect", "run", sys.executable, str(probe))
 print("skip-observed:", "probe=skip code=125" in run.stdout)
 print("first-bad-correct:", git("rev-parse", "refs/bisect/bad").stdout.strip() == commits[7])
 finally:
 git("bisect", "reset")
 git("bisect", "start", commits[-1], commits[0])
 try:
 before = git("bisect", "log").stdout
 fatal = git("bisect", "run", sys.executable, "-c", "raise SystemExit(200)", check=False)
 print("fatal-did-not-classify:", fatal.returncode != 0 and git("bisect", "log").stdout == before)
 finally:
 git("bisect", "reset")
 print("original-checkout-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 observations should print True. The runner confirms both endpoints, encounters the skip code, and still identifies revision seven. A second search deliberately exits 200; it must fail without adding a classification to the bisect log. Both searches reset to the original branch and tip afterward.

This fixture verifies automation semantics, including an unknown revision and a fatal harness result. Its state file is deliberately synthetic, not a claim to test an application’s behavior. For a real regression, replace that predicate with the independently verified reproduction while preserving the distinctions among good, bad, untestable, and broken test infrastructure.

Sources

Git bisect reference, runner exit codes, skipped revisions, search logs, and reset behavior, checked 2026-09-07.
Pro Git: debugging with Git, establishing endpoints and automating a regression search, checked 2026-09-07.

Git tags pin a release to a commit

Fri, 11 Jun 2027 00:00:00 +0000

A release tag gives people a readable name for a particular source revision. Unlike a branch, it does not advance when another commit is created. However, Git does not make a tag reference physically impossible to change: a user with sufficient access can replace or delete it. The dependable release contract is therefore a combination of a recorded object ID, an immutable-name policy, and controls over who may update release references.

Two kinds of tags

A lightweight tag is a reference directly naming an object, usually a commit. An annotated tag names a separate tag object containing a target, tagger identity, timestamp, message, and optionally a signature. The identity is the person making the tag, which need not be the commit’s author. An annotated tag is not automatically signed just because it contains this metadata.

For an annotated release, git rev-parse refs/tags/v2.4.1 identifies the tag object, while git rev-parse 'refs/tags/v2.4.1^{commit}' resolves its target commit. Record both when annotation or signature identity matters. Checking only the commit misses changes to the tag message or signer; checking only the readable name does not establish either identity.

Why sign a release

git tag -v verifies a signed tag using the configured signing backend and locally available trust information. A successful cryptographic check is useful only if the key is also one your release policy authorizes. A mathematically valid signature from an unknown person does not establish that the project’s maintainer approved the release.

A signed source tag also does not prove that a downloaded binary was built from that source. Artifact checksums, provenance, and the build process establish that separate relationship. Do not pipe verification through head and then trust the pipeline’s last exit status: truncating the display can conceal the verifier’s failure. Capture and enforce the verification command’s own result.

Move with care

Correcting an unpublished local tag is different from replacing one that consumers already fetched. Once distributed, prefer a new version name and document the withdrawn release. A security fix does not require rewriting the old tag; preserving the original reference makes affected deployments easier to identify. Server-side protection should reject unauthorized release-tag updates and deletions.

If an exceptional replacement is approved, publish the exact old and new object IDs and coordinate that single reference with consumers. A blanket forced fetch of every tag can overwrite unrelated local references and should not be routine repair advice. Consumers should never discover silently that two different commits were both presented as the same release.

When it breaks

A floating name such as latest can resolve differently between builds. Record the resolved commit with every artifact and deployment, even if a convenience name is displayed to humans. Reusing a name does not make two builds identical, and pinning a commit does not by itself freeze external dependencies or compiler versions.

Another failure is a release tag available only in one local clone. Ordinary branch pushes do not necessarily transfer it. --follow-tags concerns qualifying annotated tags reachable from the pushed commits, not every local tag. Verify the exact remote reference and its object ID with git ls-remote --tags; a substring match on the version name can accidentally accept another release. Remote visibility proves distribution, not build correctness or signature trust.

Check it quickly

Run this with Python 3 and Git. It creates an isolated temporary repository, supplies an example identity, disables signing for the demonstration, and creates no remote. It never tags the surrounding project. Python removes the disposable repository afterward.

import os
import subprocess
import tempfile

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-tag-demo-") as directory:
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Tag Example",
 "-c", "user.email=tags@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false",
 "-c", "core.hooksPath=/dev/null", *args],
 cwd=directory, env=env, text=True, capture_output=True, check=check,
 )

 git("init", "-q")
 git("commit", "--allow-empty", "-qm", "first")
 first = git("rev-parse", "HEAD").stdout.strip()
 git("tag", "-a", "demo-v1", "-m", "example release")
 git("tag", "demo-bookmark")
 print("annotated:", git("cat-file", "-t", "demo-v1").stdout.strip())
 print("lightweight:", git("cat-file", "-t", "demo-bookmark").stdout.strip())
 git("commit", "--allow-empty", "-qm", "second")
 target = git("rev-parse", "demo-v1^{commit}").stdout.strip()
 print("tag-still-first:", target == first)
 print("head-moved:", git("rev-parse", "HEAD").stdout.strip() != first)
 verification = git("tag", "-v", "demo-v1", check=False)
 print("unsigned-rejected:", verification.returncode != 0)

Expect object types tag and commit, followed by three True results. A new commit advances the branch without moving the tag, and an unsigned annotation fails signature verification. The exercise intentionally does not demonstrate a trusted signature or remote publication; those need the project’s authorized key policy and actual remote-reference checks.

Sources

git-tag reference, tag objects and the consequences of replacing a distributed tag, checked 2026-09-07.
Git tagging basics, lightweight and annotated tags plus sharing behavior, checked 2026-09-07.

A git branch is a moving label on a commit

Fri, 05 Feb 2027 00:00:00 +0000

A Git branch names the tip of a line of history. Creating another branch normally adds a reference to an existing commit, not another copy of every tracked file. Two names can point to the same commit and later advance independently. This makes branches inexpensive to create, but it does not mean their names contain the history or that deleting every reference to a commit is harmless.

A reference, not a storage format

A local branch lives in Git’s reference namespace under refs/heads/. Its representation is an implementation detail: references can be loose, packed, or stored by another supported backend. Do not edit a presumed file in .git/refs/heads to manipulate a branch. Git’s reference commands handle the repository’s actual storage and update rules.

Commits refer to trees and parent commits. Following those parent links gives the history reachable from a branch tip. Two branches can therefore share most of their history while disagreeing at their tips. The branch name is not part of a commit’s identity, and creating or renaming a branch does not rewrite the referenced commit.

Creating a branch is different from checking it out. git branch topic creates the name at the current commit but leaves the current branch unchanged. git switch topic selects that branch and updates the working tree as needed. git switch -c topic combines creation and selection. Check the active branch before recording work, rather than assuming a creation command also switched it.

HEAD explains which name moves

In normal attached operation, HEAD symbolically refers to the current branch. Creating a commit updates that branch to the new commit; other branches sharing the old tip stay where they were. The new commit’s parents preserve its ancestry. A branch can also move through merge or other explicit reference-changing operations, not only through ordinary commits.

Checking out a commit directly can detach HEAD. New commits then advance HEAD without advancing a local branch. Those commits are real, but switching away can leave them without a durable branch name. Create a branch at the desired commit before leaving, or use a known object ID to name it afterward. Reflogs can help recovery, but retention and garbage collection make them an unsuitable permanent storage promise.

Remote-tracking references such as origin/main are local observations of a remote, normally updated by fetch. They are not a live connection or the same reference as local main. An upstream configuration describes a relationship used by commands; it does not automatically synchronize the two tips whenever either side commits.

When it breaks

Uncommitted changes belong to the working tree and index, not to a saved branch snapshot. A switch can carry compatible changes along or refuse when it would overwrite them. Inspect git status and preserve outstanding work deliberately. Creating a branch name alone does not save edits that were never committed.

Deleting a branch removes a reference, not an instruction to immediately erase every object it reached. Other references may keep those commits reachable. However, commits with no remaining retention path can eventually be pruned. Git’s branch -d checks whether the branch is merged into its configured upstream, or HEAD when no upstream is configured. This guard is not a test that the resulting application behaves correctly.

A merge is also more than adding a label. A fast-forward moves an existing reference; a merge of diverged histories normally creates a commit containing a resulting tree and multiple parents. Parent reachability preserves historical objects, not a guarantee that every contribution survives correctly in the merged files. Review content as well as the graph.

Check it quickly

Run this with Python 3 and Git 2.28 or newer. It creates only empty commits in a private temporary repository. Personal Git configuration and inherited Git routing variables are excluded, hooks and signing are disabled, and no remote is configured. The deletion attempt concerns only the disposable demonstration branch.

import os
import subprocess
import tempfile

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-branch-demo-") as directory:
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Branch Example",
 "-c", "user.email=branch@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=directory, env=env, text=True, capture_output=True, check=check,
 )
 git("init", "-q", "-b", "main")
 git("commit", "--allow-empty", "-qm", "base")
 base = git("rev-parse", "HEAD").stdout.strip()
 git("branch", "topic")
 print("created-without-switch:",
 git("symbolic-ref", "--short", "HEAD").stdout.strip() == "main")
 print("same-tip:", git("rev-parse", "topic").stdout.strip() == base)
 git("switch", "-q", "topic")
 git("commit", "--allow-empty", "-qm", "topic work")
 topic = git("rev-parse", "HEAD").stdout.strip()
 print("only-topic-moved:", topic != base
 and git("rev-parse", "main").stdout.strip() == base)
 git("switch", "-q", "--detach", "HEAD")
 git("commit", "--allow-empty", "-qm", "detached work")
 detached = git("rev-parse", "HEAD").stdout.strip()
 print("detached-without-moving-topic:",
 git("symbolic-ref", "-q", "HEAD", check=False).returncode == 1
 and git("rev-parse", "topic").stdout.strip() == topic)
 git("branch", "rescue", detached)
 git("switch", "-q", "main")
 print("unmerged-delete-refused:",
 git("branch", "-d", "topic", check=False).returncode != 0)
 print("rescued-commit:", git("rev-parse", "rescue").stdout.strip() == detached)

All six checks should print True. Creating topic leaves main selected; committing on topic moves only that name. A detached commit leaves topic unchanged, and rescue then names the detached result. Deleting topic from unmerged main is refused, despite another reference retaining the history. These observations separate current-branch selection, commit reachability, and deletion policy without changing the surrounding project.

Sources

Pro Git: branches in a nutshell, branch tips, HEAD, and shared ancestry, checked 2026-09-07.
Git branch reference, branch creation, upstream relationships, and deletion checks, checked 2026-09-07.

Credentials belong outside repository history

Mon, 14 Sep 2026 00:00:00 +0000

A credential committed to Git becomes part of a versioned object graph that collaborators and automation may copy. Removing the file from the latest tree does not remove the earlier commit containing it. The practical boundary is to keep credential values out of source history and provide them through an authorized runtime mechanism. Repository configuration can describe how to obtain a secret without containing the secret itself.

When it breaks

A clean checkout can conceal an exposed historical value. A new clone normally receives reachable history, including old versions of a deleted file. Git does not literally preserve every object forever under every cleanup policy, but deleting today’s file is not history cleanup. Rewriting one repository also cannot recall independent clones, forks, caches, or artifacts already distributed.

For a real exposure, first revoke or replace the affected credential and assess which systems accepted it. Removing a line changes publication, not authentication. Coordinate any history rewrite separately because it changes commit identities and can disrupt collaborators. Avoid reproducing the value in an issue, commit message, scanner report, or incident note while explaining what happened.

Runtime injection is not automatically confidential. Environment values can be inherited by child processes or captured by diagnostics; files can be read by identities that have sufficient access. Restrict the consuming service’s permissions, control the delivery channel, and keep secret values out of logs and generated output. A file outside the repository still needs an explicit owner and lifecycle.

Check it quickly

Run this Python script on a POSIX system with Git installed. It uses a plainly synthetic marker, never a working credential, and creates both repositories and runtime files inside one temporary directory. System and global Git configuration are disabled for the subprocesses. The recorded run used Git 2.50.1:

from pathlib import Path
from tempfile import TemporaryDirectory
import io,os,stat,subprocess,sys,tarfile

env=dict(os.environ,GIT_CONFIG_NOSYSTEM='1',GIT_CONFIG_GLOBAL=os.devnull)
with TemporaryDirectory(prefix='credential-repo-lab-') as directory:
 base=Path(directory);repo=base/'source';repo.mkdir()
 def git(*args,cwd=repo,binary=False):
 result=subprocess.run(['git',*args],cwd=cwd,env=env,capture_output=True,text=not binary)
 assert result.returncode==0,result.stderr
 return result.stdout
 git('init','-q');git('config','user.name','Credential Lab')
 git('config','user.email','credentials@example.invalid')
 git('config','commit.gpgsign','false')
 dummy='EXAMPLE-ONLY-NOT-A-REAL-SECRET\n'
 (repo/'fixture.env').write_text(dummy)
 (repo/'app.txt').write_text('read the configured credential file at runtime\n')
 git('add','--','fixture.env','app.txt');git('commit','-qm','Synthetic exposure fixture')
 original=git('rev-parse','HEAD').strip()
 git('rm','--','fixture.env');git('commit','-qm','Remove fixture from current tree')
 assert not (repo/'fixture.env').exists()
 assert git('show',original+':fixture.env')==dummy
 clone=base/'clone';git('clone','-q','--no-local',str(repo),str(clone))
 assert not (clone/'fixture.env').exists()
 assert git('show',original+':fixture.env',cwd=clone)==dummy
 print('current file absent; historical fixture readable in source and clone')
 archive=git('archive','--format=tar','HEAD',binary=True)
 with tarfile.open(fileobj=io.BytesIO(archive),mode='r:') as bundle:
 assert bundle.getnames()==['app.txt']
 print('current-tree archive excludes fixture; Git history still contains it')
 runtime=base/'runtime';runtime.mkdir(mode=0o700)
 secret_file=runtime/'credential';secret_file.touch(mode=0o600)
 secret_file.write_text(dummy)
 assert stat.S_IMODE(secret_file.stat().st_mode)==0o600
 child_env=dict(env,CREDENTIAL_FILE=str(secret_file))
 child="from pathlib import Path; import os; p=Path(os.environ['CREDENTIAL_FILE']); assert p.read_text(); print('credential loaded without printing its value')"
 result=subprocess.run([sys.executable,'-c',child],cwd=clone,env=child_env,text=True,capture_output=True)
 assert result.returncode==0,result.stderr
 assert dummy.strip() not in result.stdout+result.stderr
 print(result.stdout.strip())

The first result confirms that the fixture is absent from both current working trees while its original content remains readable through the earlier commit in both repositories. The clone uses the normal Git transfer path rather than local hardlink optimization, so this checks a separately populated object database. The script compares the marker internally and does not print its value.

The current-tree archive contains only the application description. This proves that exporting one clean tree can exclude a deleted file while the repository history still contains it. It does not prove that every packaging method is safe: a build script may include other inputs, copy repository metadata, or embed a secret supplied during compilation.

The runtime example creates a private directory and a credential file with owner-only read and write permissions. A child process receives the file path through its environment, reads the file, and prints only confirmation. The assertion rejects accidental marker output. This demonstrates separation from the source tree and ordinary POSIX permissions, not a full secrets service, encrypted storage, or protection against the same operating-system identity.

Make delivery and recovery explicit

Commit a configuration schema or example containing names and harmless placeholders. Provision the actual value through the deployment platform or a secrets service with narrowly scoped access. Prefer an established workload identity when the platform supports it, so obtaining one credential does not require permanently distributing another powerful bootstrap secret. Decide how applications reload replacement values and how old access is revoked.

Place secret detection where it can prevent routine mistakes, such as before a commit and during CI, and verify it with appropriate synthetic fixtures. Pattern and entropy scanners can miss credentials they do not recognize and can also flag harmless examples. Treat their output as evidence to investigate, not proof that an unflagged repository is safe or permission to suppress broad categories indiscriminately.

Inspect actual release archives, container layers, build logs, caches, and diagnostic attachments according to the delivery path in use. A Git exclusion rule does not automatically govern those other outputs. Record affected credential identifiers and revocation evidence without copying the values. A successful repair combines invalidated access, controlled replacement, and understood distribution; a deletion commit alone establishes only that the latest tree changed.

Sources

GitHub sensitive-data removal, revocation before coordinated history cleanup and distributed-copy limits, checked 2026-09-12.
OWASP secrets management, delivery, least privilege, logging, and credential lifecycle, checked 2026-09-12.
git archive, exporting a selected repository tree, checked 2026-09-12.

Git · XB Field Notes

Merge and rebase draw different history lines

What a merge records

What a rebase changes

When it breaks

Check it quickly

Sources

Git merge joins two diverged lines at a new commit

Parents preserve history, not a single timeline

Review the tree before recording the join

When it breaks

Check it quickly

Sources

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 git worktree checks out two branches at once

Identify the state that belongs to each checkout

Shared does not mean every item is shared

When it breaks

Check it quickly

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

git bisect automates a regression search

Establish a reproducible question

Map results to bisect’s actual contract

When it breaks

Check it quickly

Further reading

Sources

Git tags pin a release to a commit

Two kinds of tags

Why sign a release

Move with care

When it breaks

Check it quickly

Further reading

Sources

A git branch is a moving label on a commit

A reference, not a storage format

HEAD explains which name moves

When it breaks

Check it quickly

Sources

Credentials belong outside repository history

When it breaks

Check it quickly

Make delivery and recovery explicit