Comprehensive Analysis of Commit Migration Using Git rebase --onto

Problem Scenario Analysis

In distributed version control systems, branch management constitutes a fundamental aspect of daily development workflows. Consider the following typical scenario: the main branch master is at commit X, while the feature branch quickfix1 has two additional commits q1a and q1b based on master. The branch structure can be represented as:

o-o-X (master HEAD)
     \
      q1a--q1b (quickfix1 HEAD)

When a developer accidentally creates a new branch quickfix2 based on quickfix1 and adds commits q2a and q2b, the branch dependency relationship becomes:

o-o-X (master HEAD)
     \
      q1a--q1b (quickfix1 HEAD)
              \
               q2a--q2b (quickfix2 HEAD)

This incorrect dependency causes quickfix2 to include commits from quickfix1 that don't belong to its functional scope, requiring technical intervention for correction.

Core Solution with rebase --onto

The git rebase --onto command is specifically designed to address such branch dependency correction issues. Its basic syntax structure is:

git rebase --onto <newbase> <upstream> <branch>

The command semantics are: replay all commits from <branch> that come after <upstream>, rebasing them onto <newbase>. For the described problem scenario, the specific operational workflow is:

# Switch to target base branch
git checkout master

# Execute rebase --onto operation
git rebase --onto master quickfix1 quickfix2

Upon execution, Git performs the following sequence: first identifies the commit differences between quickfix1 and quickfix2 (i.e., q2a and q2b), then reapplies these commits based on the master branch, generating new commits q2a' and q2b'. The final branch structure becomes:

      q2a'--q2b' (quickfix2 HEAD)
     /
o-o-X (master HEAD)
     \ 
      q1a--q1b (quickfix1 HEAD)

Technical Principle Deep Dive

The implementation of rebase --onto is based on Git's commit graph traversal algorithms. When executing the command, Git first calculates three key parameters:

1. <newbase>: The new base commit determining the starting point for replaying commits
2. <upstream>: The upstream branch defining the commit range to exclude
3. <branch>: The target branch containing the commits to migrate

The core algorithm steps include: identifying the commit set of <upstream>..<branch>, replaying these commits in topological order onto <newbase>, and resolving potential merge conflicts. Unlike simple cherry-pick operations, rebase --onto preserves complete commit history relationships and metadata information.

Alternative Approach Comparative Analysis

Beyond rebase --onto, developers may consider the following alternative approaches:

Approach 1: Selective Commit Picking with cherry-pick

git checkout -b new_quickfix2 master
git cherry-pick q2a q2b

This method selectively applies specific commits individually, suitable for simple scenarios but incapable of handling complex dependencies and loses original commit metadata.

Approach 2: Range-based Cherry-pick Operation

git cherry-pick quickfix1..quickfix2

This command selects all commits from after quickfix1 to quickfix2, offering concise syntax but limited functionality, unable to specify a new base branch.

Comprehensive comparison reveals that rebase --onto demonstrates clear advantages in maintaining historical integrity, handling complex dependencies, and specifying new bases, making it the recommended solution for such problems.

Best Practices and Considerations

When performing rebase --onto operations, adhering to the following best practices is recommended:

1. Working Directory Cleanliness Check: Ensure no uncommitted changes exist in working directory and staging area, verifiable via git status
2. Auto-stash Configuration: Set git config --global rebase.autostash true, supported in Git 2.10 and later for automatic stashing of uncommitted changes
3. Conflict Resolution Strategy: Prepare for potential merge conflicts, as the rebase process pauses at each commit application awaiting conflict resolution
4. Backup Measures: Before operating on critical branches, create backup branches: git branch quickfix2_backup quickfix2

By systematically mastering rebase --onto technology, developers can effectively manage complex branch dependency relationships, enhancing the efficiency and reliability of version control workflows.