Things I ask AI

An orphan branch with worktree

Using git, how do I incorporate an orphan branch and a new worktree?

Using Git orphan branches together with worktrees is a great way to maintain a completely separate history (like docs, generated files, or experiments) while working in parallel directories. Below is the typical workflow.

1. Create an Orphan Branch

An orphan branch starts with no history—its first commit becomes the root commit.

git checkout --orphan new-branch

At this point:

Usually you clear the working tree:

git rm -rf .

Then add your new files:

echo "# New project" > README.md
git add .
git commit -m "Initial commit on orphan branch"

Now new-branch has its own independent history.

2. Create a Worktree for the Orphan Branch

Worktrees allow you to check out multiple branches simultaneously in separate folders.

Create one:

git worktree add ../new-branch-dir new-branch

Result:

repo/
repo/.git
repo/   -> current branch (e.g., main)

../new-branch-dir/
    working tree for new-branch

Now you can work on both branches at the same time.

3. Creating the Orphan Branch Directly as a Worktree

A cleaner workflow is:

git worktree add --orphan ../new-branch-dir new-branch

Then inside the new directory:

cd ../new-branch-dir
git rm -rf .
# add files
git add .
git commit -m "Initial orphan commit"

This creates:

in one step.

4. Typical Use Cases

Use case Why orphan branch
gh-pages site separate site history
generated docs avoid polluting main history
experiments isolated commits
deployment artifacts independent lifecycle

Example:

repo/
repo/ (main code)

../repo-docs/ (docs orphan branch)

5. View Existing Worktrees

git worktree list

Example output:

/repo                a1b2c3 [main]
/repo-docs           d4e5f6 [docs]

6. Remove a Worktree

git worktree remove ../new-branch-dir

The branch itself is not deleted.

💡 Best Practice

For things like documentation or static builds:

git worktree add --orphan ../site gh-pages

This keeps your site files completely separate from your main history.

✅ If you want, I can also show:

After running git worktree add --orphan ../new-branch-dir new-branch, I get fatal: option '--orphan' and commit-ish cannot be used together

That error happens because git worktree add expects a starting commit when you provide a branch name, and --orphan means “no starting commit”. So Git sees both and complains.

In short:

--orphan  => no parent commit
new-branch => implies a commit-ish

So this command fails:

git worktree add --orphan ../new-branch-dir new-branch

because new-branch is interpreted as a commit/branch to base the worktree on.

Correct Workflow

Create the worktree first, then create the orphan branch inside it.

1️⃣ Create the worktree

git worktree add ../new-branch-dir

This creates a worktree at the current HEAD.

2️⃣ Switch to an orphan branch inside the worktree

cd ../new-branch-dir
git switch --orphan new-branch

(or older Git)

git checkout --orphan new-branch

3️⃣ Clear inherited files

The working tree still contains files from the original branch.

git rm -rf .

4️⃣ Create the first commit

echo "# new branch" > README.md
git add .
git commit -m "Initial orphan commit"

Now:

Alternative (One Command + One Switch)

Some people prefer:

git worktree add -b new-branch ../new-branch-dir

Then reset history:

cd ../new-branch-dir
git switch --orphan new-branch
git rm -rf .

Verify

Run:

git log --oneline --graph --all

You should see two unrelated roots.

✅ Common real-world uses for this pattern

If you want, I can also show a very clean pattern for maintaining an orphan site or docs branch with a worktree that avoids ever touching your main repository directory. It's a trick many projects use.

WARNING: AI can and will make mistakes. It is the user's responsibility to not blindly copy and paste anything from an AI engine into any production environment.