Merge · 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.