checkout an orphan branch

[Midnighter]

Just wanted to leave a note since I couldn't find documentation on it anywhere and it took me a while to figure it out. In order to checkout an orphan branch named, for example, gh-pages, run:

repo.active_branch.checkout(orphan="gh-pages")  # or: repo.head.ref.checkout

[Midnighter]

But annoyingly although the branch is created I get a ValueError for the reference:

ValueError: Reference at 'refs/heads/gh-pages' does not exist

so I cannot delete the git cached files.

[Byron]

Thanks for posting! Could you provide a script that helps to reproduce the issue?
Just running the first provided line (repo.active_branch.checkout(orphan="gh-pages")) doesn't do it for me.

Thank you

[Midnighter]

The workflow that I would like to copy with gitpython is:

# set up repository
git init
git add "."
git commit -m "feat: add initial structure"

# setup up deploy branch
deploy_branch="gh-pages"
git checkout --orphan "${deploy_branch}"

# clear files
git rm -r --cached "."
old_ignore=${GLOBIGNORE}
GLOBIGNORE=".git"
rm -rf * .*
GLOBIGNORE=${old_ignore}
mkdir "Results"
touch "Results/.keep"
echo "Soon(tm)" > "index.html"
git add --all "."
git commit -m "feat: add initial \`${deploy_branch}\` structure"

When I go through the same steps using gitpython, I run into the problem that the branch is not considered valid. I'll dig out that script, give me a moment.

[Midnighter]

Here's a Jupyter notebook showcasing the error I came across. Maybe I'm just too new to using gitpython but it seems like an issue to me. Using GitPython==2.1.3.

[Midnighter]

@Byron do you need any more information from me?

[Byron]

@Midnighter Thanks a lot! I think now there is enough information to pick up the issue.

[jaitaiwan]

I need this functionality for a work script I'm writing. If someone wants to point me in the right direction towards a fix I can get cracking on a pr?

[jaitaiwan]

@Midnighter I did some more research and under the hood it seems that when doing an orphan checkout the branch is not actually created. The branch will only exist after the first git commit in which case the refs/heads/ will point to the newly created commit with no parents.

[jaitaiwan]

This is explained here: https://stackoverflow.com/questions/47078961/create-an-orphan-branch-without-using-the-orphan-flag

So unless I'm mistaken this would actually end up being expected functionality...

[jaitaiwan]

Ok I've finished experimenting and I've found a way of creating orphan branches.

from os import getcwd
from git import Repo, Head

orphan_branch = 'lumberjack'
r = Repo(getcwd())
# Change the head reference to the new branch
r.head.reference = Head(r, 'refs/heads/'+orphan_branch)

# Do whatever you need to, to make the index what you want
index = r.index # apparently r.index recreates the index everytime
index.remove(['foo.txt'])
index.commit("Test commit message", parent_commits=None) # The orphan branch is created at this step

[jaitaiwan]

@Byron I'm not sure if this needs to be encapsulated in a function... but what I can say is that this functionality isn't always immediately obvious and the documentation on how orphan branches were created in git is hard to find, so I'm not sure if an example in the documentation might be needed.