Complete Guide to Moving Changes from Master to a New Branch in Git

Introduction

Branch management is a fundamental feature of the Git version control system in software development. A common scenario occurs when developers inadvertently make modifications on the wrong branch (e.g., master) and need to migrate these changes to a new branch while restoring the original branch to its pristine state. This article systematically details the technical aspects and implementation methods based on community-approved best practices.

Core Concepts and Prerequisites

Before initiating migration, it is crucial to determine whether changes have been committed. This decision influences the subsequent steps. Git records file states through snapshots, so migration essentially involves copying specific commits or staged content to a new branch reference.

First, use the git status command to inspect the current working directory state. If the output shows "Changes not staged for commit" or "Changes to be committed," uncommitted changes exist; if it displays "nothing to commit, working tree clean," all changes are committed.

Scenario 1: Handling Uncommitted Changes

When changes are not yet committed, switching branches directly would result in loss of working directory content. Git's stash functionality provides a temporary storage mechanism for such cases.

Step 1: Execute git stash. This command saves modifications from the working directory and staging area to the stash stack, reverting to the state of the most recent commit. Internally, Git creates special commit objects to store the change content.

Step 2: Create and switch to a new branch. Use git checkout -b newbranchname, where the -b parameter indicates branch creation, and newbranchname is a custom branch name. This command creates a new branch reference based on the current commit.

Step 3: Restore the stashed content. Execute git stash pop to apply the most recent stash to the current branch and remove it from the stack. To retain the stash record, use git stash apply instead.

Code example:

# Save uncommitted changes
git stash
# Create and switch to a new branch
git checkout -b feature-branch
# Restore changes
git stash pop

This method is suitable for temporary change migration but note that stashes do not include untracked files (new files), which require additional handling.

Scenario 2: Handling Committed Changes

When changes are already committed, migration involves redirecting branch references. The best practice employs a combination of branch creation and reset operations.

Assume the current master branch is at commit 6, and you need to create a new branch pointing to 6 while resetting master back to the original commit 3. The commit history can be simplified as:

---- 1 ---- 2 ---- 3 ---- 4 ---- 5 ---- 6
                   ^                    ^
              original                master
            master commit

Step 1: Create a new branch pointing to the current commit. Use git branch ticket, where ticket is the new branch name. This command creates a branch reference at the current position without switching the working directory.

Step 2: Reset the master branch. Execute git reset --hard 3 to move the master branch reference to commit 3 and forcibly update the working directory and staging area. The --hard parameter indicates that changes from subsequent commits are permanently discarded.

Step 3: Switch to the new branch. Use git checkout ticket to complete the migration.

Complete code example:

# Create a new branch pointing to the current commit
git branch ticket
# Reset master to the original commit
git reset --hard 3
# Switch to the new branch
git checkout ticket

The key to this method is accurately identifying the target commit hash. Use git log --oneline to view commit history or relative references like HEAD~3 to denote three commits back.

Method Comparison and Considerations

The stash method is ideal for uncommitted changes, offering simplicity but potentially omitting new files. The reset method suits committed changes, allowing precise control over branch history, but caution is advised with the --hard parameter due to permanent data loss.

Supplementary approaches: If new files exist, stage them with git add before stashing or use git stash -u to include untracked files. For committed changes, git cherry-pick can selectively migrate specific commits, though it increases complexity.

Safety recommendations: Before resetting, use git reflog to log reference changes for recovery in case of errors. In collaborative environments, if branches have been pushed remotely, consider the risks of git push --force and test locally first.

Conclusion

Git branch migration is a common requirement in version control, with the appropriate method depending on change status and project context. For uncommitted changes, prioritize the stash mechanism; for committed changes, adopt the branch creation and reset strategy. Developers should deeply understand Git's object model and reference mechanisms, validate operations with tools like git status and git log, and ensure consistency and traceability in version history.