Create an orphan branch without using the orphan flag

Question

I have an existing repo with some branches. I want to create a new branch without any history on that repo. I'm trying to do this using Dulwich, which supports most git operations, though not the orphan flag.

What are the equivalent Git operations to create an orphan branch without actually using that flag? Ideally i'd like to:

• clone the repo
• make a new branch with the contents of the repo, but without history
• push the branch to the repo

Is this possible or do I need to create a new branch that's empty, clone to a separate directory and copy the contents back?

Answer 1

Note: I don't use Dulwich and cannot say for sure anything about it. Depending on how much of Git it re-implements from scratch, what Git does may be irrelevant.

An orphan branch, in Git, is actually a branch that doesn't exist. What git checkout --orphan newbranch does is to write the name newbranch into HEAD, without actually creating newbranch.

More specifically, aside from consistency and error checking,¹ the difference between:

git checkout -b newbranch

and:

git checkout --orphan newbranch

is that the former runs:

git update-ref refs/heads/newbranch HEAD && \
git symbolic-ref HEAD refs/heads/newbranch

and the latter runs:

git symbolic-ref HEAD refs/heads/newbranch

The first step, git update-ref, actually creates the branch.

The second step, git symbolic-ref, sets us up to be "on" the branch.

An orphan branch, then, is one that we are "on" that does not exist.

The actual branch creation happens later, when we make a new commit. So it's not git checkout that creates these; it's git commit! The commit operation fundamentally consists of:

1. turn the current index into a tree object (git write-tree);
2. find the parent ID(s) for the current commit (read HEAD and check for pending merges);
3. collect the remaining metadata (author, committer, email addresses ,time stamps, log message);
4. create a commit object that has the information from the earlier steps;
5. write the new commit object's hash ID through HEAD into the current branch name (or directly into HEAD if HEAD is detached).

Step 5 is where the branch gets created. During step 2, if HEAD names a branch that does not exist, it contributes no parent hash ID, so that the new commit has no parents (presumably there are no recorded additional parents for merges at this time).

If Dulwich behaves the same as Git here—it very well might, because this peculiar state, of being on a branch that does not exist, is how Git bootstraps an empty repository, and it's the obvious way to do it—then all you have to do to implement what you want directly is to rewrite the HEAD information (however Dulwich stores it) so that it points to this non-existent branch.

---

¹git checkout -b newbranch also offers git checkout -b newbranch startpoint. Using a different starting point has a whole cascade of side effects: Git first attempts to do git checkout startpoint internally, which may make arbitrary modifications to index and work-tree.