Version-Control · XB Field Notes

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.

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.