1. LandOffer
  2. Blog
  3. All articles
  4. Rebase or Merge Before a Pull Request? Preserve the History Your Team Needs

Engineering Practice

Rebase or Merge Before a Pull Request? Preserve the History Your Team Needs

Choose rebase or merge by shared dependencies and team policy. An executed local example compares histories, catches a semantic conflict and verifies the integrated result.

9 min readLandOffer team

Before choosing rebase or merge, find out whether anyone relies on the commits you would replace and what history your team expects to review. Rebase can replay private work onto a newer base; merge can incorporate the base while retaining the existing commits. Neither choice resolves the meaning of a conflict or proves the resulting code is correct. Inspect the branch, follow the team policy and retest the integrated behavior before opening the pull request.

This LandOffer.ai guide includes an actually executed, isolated Git example with synthetic code. No shared repository, remote branch or pull request was changed. Its commands and observations illustrate the decision; they are not an instruction to rewrite an existing team branch without agreement.

A woman holds joined patterned fabric while a man aligns another strip on navy cloth at a textile worktable.

Check who depends on the history

Identify the branch's role and its consumers before choosing a history shape. Is it private work that nobody has fetched? A shared feature branch with another developer's dependent commits? A protected integration branch? Ask dependent developers and existing draft reviewers whether they rely on the current commits.

Pro Git's rebasing chapter warns against rebasing commits that others may have based work on. Replaying a similar change creates a different commit; a colleague's branch still refers to the earlier history. Merely calling a branch “mine” does not establish that nobody else depends on it.

Check the repository's contribution instructions and required merge strategy. Some teams accept merge commits on feature branches; others require a linear history. A hosting platform's final pull-request integration option is also distinct from how you update the feature branch before review. Do not infer one policy from the other.

If sharing is unknown, record that uncertainty before deciding. In Ravi's planning record, an unanswered message from Yuna would leave the private-branch assumption unconfirmed. Ravi can inspect local references, but their absence cannot prove that nobody copied a commit into another repository. He asks Yuna and the reviewer directly and keeps the original tip available while waiting. The cost of clarifying ownership is part of the decision, not a reason to assume exclusive use.

This also separates publication from current dependency. A branch pushed for backup may have no known consumers, while a patch copied privately to a colleague may already have one. The relevant question is who relies on the history and what updates they have agreed to handle. A team-approved rewrite needs that coordination as well as the repository's technical permissions.

If the branch is shared and the policy seems incompatible with preserving it, coordinate with the owner before acting. An agreed new branch or another team-approved approach may be preferable. Force-updating a remote is a separate action with consequences for collaborators; this article does not provide a force-push recipe.

The same starting history, two possible outcomes

The original toy repository has a function called join_tags. Commit B joins labels with commas. A feature branch adds whitespace trimming in F, then explains trimming in a notes file in D. Meanwhile, main changes the separator to a semicolon in U. The function is deliberately small so the conflict's meaning is visible; it is not a production serialization format.

The symbolic before-and-after diagrams correspond to the recorded local histories. Letters name roles in this example, not actual Git object identifiers.

Before either operation:

B---U          main
 \
  F---D        feature

Merge main into feature:

B---U---------M  feature
 \           /
  F---D-----/

Rebase private feature onto main:

B---U---F'---D'  feature

In the actual run, merge commit M has D and U as its two parents. F and D retain their identities. The rebase produces F′ and D′ on top of U, with new identifiers; the original commits remain reachable through a deliberately saved local reference in the fixture.

Git's merge manual describes integrating changes from diverged histories. This particular example requires a merge commit because the tips diverged. It is not a claim that every git merge creates one: a fast-forward can simply move a branch pointer when the histories allow it.

The rebase manual describes replaying commits on a different starting point. That is why a neat linear graph does not mean the work originally happened in that order. Choose the representation that fits collaboration and repository policy, then evaluate the code independently.

A completed decision for private and shared work

Imagine engineer Ravi preparing these same feature changes for review. In the first fictional collaboration situation, Ravi confirms that the branch has never been shared and no one has based work on it. The team's instructions prefer a linear feature history. Ravi chooses rebase onto the intended current base, preserves a local recovery reference and plans to verify the result.

In a second fictional situation, colleague Yuna already has dependent work based on D and a reviewer has discussed F by commit identifier. Their team permits merging main into a feature branch. Ravi chooses merge, preserving the referenced commits and explaining the integration conflict in the review notes. Preserving F and D lets Yuna and the reviewer keep using the commit identities they already reference.

Decision field Private-work case Shared-work case
Known dependency Ravi confirms nobody relies on F or D Yuna's dependent work and review references rely on D/F
Team expectation Linear feature history Merge updates allowed on this feature branch
Chosen local operation Rebase feature onto the intended base Merge the intended base into feature
History consequence F/D replaced by F′/D′ F/D preserved; M records integration
Required follow-through Inspect replayed changes and rerun verification Explain integration resolution and rerun verification
Unresolved external step Opening/reviewing the pull request Coordinating dependent work and pull-request review

Ravi and Yuna's collaboration decisions are authored fiction, separate from the executed fixture. Only the toy Git operations and checks below were actually executed. The example does not establish a particular company's policy, branch protection or approval state.

Resolve the behavior, not just the conflict markers

Both actual paths stop on the function conflict. The feature wants trimming; main wants the new separator. Choosing the entire upstream version removes trimming, while choosing the feature version loses the separator change. A correct resolution for this synthetic requirement retains both.

def join_tags(items):
    return ";".join(item.strip() for item in items)

The expected behavior was specified independently of either side's file. Empty input produces an empty string. Plain labels join with a semicolon. Labels with surrounding spaces are trimmed before joining. Embedded separators, non-string items, escaping and domain validation are outside this example's specification.

Executed check Expected Upstream-only candidate Combined resolution
Empty list Empty string Pass Pass
['A', 'B'] A;B Pass Pass
[' A ', ' B '] A;B Fails: returns A ; B Pass

The upstream-only candidate passes two checks and still loses a feature requirement. That is why “Git accepted the resolution” is weaker evidence than “the behavior we intended survived integration.” The combined version passes all three checks on both the completed merge and completed rebase paths.

The checks are narrow. They do not prove a general serializer correct, exercise a real application or cover every conflict. For production changes, identify the behavior each side introduced, update meaningful regression tests and run the repository's appropriate verification. Do not make a failing expectation match the code merely to get a green result.

What the actual local run established

The fixture ran with Git 2.50.1, Apple Git-155, in a newly created temporary repository. It used only authored files, no remote and no inherited project hooks. The surrounding project repository was not modified. The retained transcript includes the commands, conflict contents, commit identities, final tree identifiers and test outputs.

For the merge path, a branch starting at D ran git merge --no-edit main, stopped on the expected conflict, then committed the combined resolution as M. The recorded parents are D followed by U. For the rebase path, a separate branch starting at D ran git rebase main, stopped while replaying F, accepted the combined resolution with git add labels.py and continued with git rebase --continue. D then replayed successfully.

The actual merge tip is 2156265; the replayed feature commits are 986e5b6 and 48fda27. These are short identifiers from this retained run, not identifiers readers should expect in their own repositories. Both completed paths record tree 989e85446289ef8404ce61397f9ea14975342d0f; their commit graphs differ.

A separate interrupted-rebase check began again from D, reached the conflict and ran git rebase --abort. In that controlled clean-worktree case, Git restored the original D tip and the working tree was clean. That observation does not promise recovery of arbitrary uncommitted edits. The merge manual specifically cautions that starting with substantial uncommitted changes can make reconstruction difficult.

No push, remote-policy test, hosted check, code review or pull-request merge occurred. Those remain separate from the local result. The temporary repositories were discarded after their relevant evidence was saved.

Hands align rust and sage fabric strips over navy cloth, beside visible stitches, a needle and a spool.

Prepare the branch before review

Before an integration operation, inspect the current branch, worktree state, target base and uncommitted changes. Preserve work through your team's normal process before starting. Confirm the intended base is current through the authorized repository workflow; the toy's local main is not a substitute for checking your actual remote-tracking references.

During a stopped rebase, inspect the current patch and conflict before staging a resolution. Continuing tells Git you resolved that step; it does not tell you the code is semantically correct. Skipping a commit discards its replayed change, so do not use skip merely to silence a conflict you have not understood. If the operation no longer matches the intended plan, stop and use the appropriate documented recovery route.

After integration, review the entire feature difference against the intended base, not only the conflict file. Compare the original intent with the integrated difference and investigate any missing, duplicated or unexpectedly broadened change. Inspect history as well as content, then run the verification appropriate to the updated head. Earlier checks apply to earlier code and cannot establish the final integrated result.

If the main branch advances again, assess the repository's freshness requirements rather than endlessly rewriting a branch for cosmetic alignment. Another update may invalidate the checks you just ran. Keep the tested head and target base clear in the review record.

Leave a useful history and verification note

For the shared-work example, Ravi's completed draft note says: “Merged main into the feature branch to preserve F and D, which Yuna's work and review comments reference. Resolved join_tags by keeping main's semicolon separator and the feature's trimming. The toy regression paths cover empty, plain and padded labels. Broader application verification and pull-request review remain pending.”

For private work, the note would instead disclose that F and D were replayed and identify the new head. Neither note should claim approval merely because the local checks passed. If a reviewer was already reading an earlier history, explain what changed so they can decide what needs another look.

Choose the operation around shared dependencies and team policy, preserve a recoverable starting point, and verify the integrated behavior. Leave the history choice, preserved behavior and remaining verification clear for reviewers. For related guides to current engineering work, visit LandOffer.ai.

Sources and Further Reading

  • Pro Git, Second Edition: Rebasing — Integration/history distinctions and the warning about rewriting commits others may depend on. Chapter undated; checked October 28, 2026.
  • Git: git-merge — Merge behavior, fast-forward distinction and uncommitted-work warning. Current manual lists its last substantive update as 2.54.0, April 20, 2026; checked October 28, 2026. Local fixture used Git 2.50.1.
  • Git: git-rebase — Replay, conflict continuation, abort and skip semantics. Current manual lists its last substantive update as 2.54.0, April 20, 2026; checked October 28, 2026. No newer-only option is required by the fixture.