Understanding orphan branches in Git

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


An orphan branch, also known as an unrelated branch, is a branch that starts from an empty state with no prior commits. When you create an orphan branch, it essentially has no parent commit, making it a root of a new history tree. This is particularly useful for starting new projects within the same repository without inheriting the commit history of the main project.

This guide explains what it means for a branch to be orphaned, the implications of using such a branch, and how to effectively manage orphan branches.

To create an orphan branch in Git, you use the git checkout command with the --orphan option. Here’s how it’s done:

Terminal
git checkout --orphan <branch_name>

Replace <branch_name> with the name of your new branch. When you switch to this orphan branch, you'll notice that while your working directory and staging area are preserved as they were, the branch itself has no commits. After executing the command, your next commit will be the root commit of this new branch, completely disconnected from all other branches and their histories.

Orphan branches can be useful, but they come with a set of considerations:

  1. Separate history: The main consequence of an orphan branch is that it shares no history with other branches. This can be advantageous for starting new sub-projects or prototypes, but it can complicate merges back into the main project since there are no common ancestors.

  2. Repository cleanliness: Having multiple orphan branches can clutter the repository, especially if they are not regularly maintained or eventually merged into a main project line.

  3. Confusion and complexity: For teams, orphan branches can introduce confusion, as the lack of shared history might make typical Git workflows (like merging and rebasing) more complex or irrelevant.

If you find yourself needing to work with or manage orphan branches, here are a few tips and commands that might help:

  1. Initializing the branch: After checking out an orphan branch, it’s a good practice to clear out the staging area (unless you intentionally want to keep files to make the initial commit):

    Terminal
    git rm -rf .

    This command removes all files from the staging area, ensuring that your new branch starts completely fresh.

  2. Making the first commit: As soon as you're ready, you can start adding new files and make the first commit:

    Terminal
    git add <files>
    git commit -m "Initial commit on orphan branch"
  3. Merging an orphan branch: Merging an orphan branch into another can be tricky since they don’t share a common history. If needed, you might consider using a strategy that ignores the lack of common ancestry:

    Terminal
    git merge <orphan_branch> --allow-unrelated-histories

    This allows Git to merge the branches despite them having no shared base.

  4. Deleting an orphan branch: If the orphan branch is no longer needed, it can be deleted like any other branch:

    Terminal
    git branch -D <orphan_branch>

For further reading on orphan branches in Git, see the official Git documentation.

On this page
Git gud
"It's the first Git workflow I've used that actually feels good."
–@robboclancy
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2