Custom workspace branches

[torarnv]

Hello 👋🏻

In my normal git workflow, I operate a local branch, say main, where I juggle a set of commits. This is my workspace. Sometimes I juggle these commits manually, and sometimes i use tools that make stacked patch management easier, but I'm still working on that branch.

I then push these commits to a target, tracked by the upstream tracking branch of my local branch, e.g. via git branch --set-upstream-to=origin/main main. The upstream tracking branch is both where I pull new changes from, and where I push my changes to (directly, or indirectly).

GitButler seems to duplicate these concepts, by defining its own workspace, gitbutler/workspace, and its own way to track what the target is, via gitbutler/target, which feels a bit strange. I generally prefer my tooling to be as nonintrusive as possible in mandating changes to existing workflows, so I'm wondering if these two "special" branches are really needed.

I understand that on the workspace branch, whatever that is, you're managing an octopus merge commit on top, and rewriting history, so for new users it might make sense to test their feet on a different branch than what they normally work on. But for more experienced users, it should be possible to take off the training wheels and work with GitButler directly on the main branch as the "workspace".

Regarding gitbutler/target, I'm wondering what purpose it serves that isn't covered by normal upstream tracking branches? With the current design, I for example can't use regular git tooling and conventions to ask what the current upstream is:

❯ git rev-parse --abbrev-ref HEAD@{upstream}
fatal: no upstream configured for branch 'gitbutler/workspace'

I know that this information is tracked internally:

❯ head .git/gitbutler/virtual_branches.toml
[default_target]
branchName = "main"
remoteName = "origin"

But would have expected this information to be available through plain git:

❯ git branch --set-upstream-to=origin/main gitbutler/workspace
branch 'gitbutler/workspace' set up to track 'origin/main'.
❯ git rev-parse --abbrev-ref HEAD@{upstream}
origin/main

And if it were (done automatically), then that goes back to the earlier question of why the gitbutler/target is needed.

These questions are extra relevant when dealing with multiple "target" branches. I often work on both main and production branches (2.0 e.g.), and have these checked out as separate git work trees. In a normal git workflow, this is straight forward, with main having origin/main as its tracking branch, and 2.0 having anotherorigin/2.0 as upstream e.g.

With the current design of GitButler it seems we're limited to a single upstream "target"?

Hope these use-cases can be taken into account for future development of GitButler, as it looks like a really cool product/project! ❤ Thanks!

[Byron]

Thanks so much for sharing!
Particularly the worktree setup you seem to be using is now a very vivid usecase that I think will work in future iterations. As worktrees are fine changing the checked-out branch to something else as long as it's not checked out anywhere else, the current worktree-branch GItButler maintains would work there, one or more per worktree (in the future). Please note that in that future, there will be no such branch unless it's truly needed, which isn't the case during the normal Git workflow anyway.

The gitbutler/target branch, @krlvi informed me, is an artefact to mostly ignore, it's not actually denoting the GitButler Target which is stored exclusively in the virtual_branches.toml file.

[torarnv]

The gitbutler/target branch, @krlvi informed me, is an artefact to mostly ignore, it's not actually denoting the GitButler Target which is stored exclusively in the virtual_branches.toml file.

Interesting. So can perhaps be removed? Or at least made into a refs/gitbutler/ to hide it? The less magic/internals/plumbing the user sees in their normal git operations/workflows the better I suppose?

[torarnv]

Here's a more complete example of my workflow today:

❯ cd dev/qt/qtbase

❯ git worktree list
/Users/torarne/dev/qt/.git/modules/qtbase    (bare)
/Users/torarne/dev/qt/5.15/qtbase            2b7d6eb6ea2 [5.15]
/Users/torarne/dev/qt/6.2/qtbase             37f05cbebe2 [6.2]
/Users/torarne/dev/qt/6.5/qtbase             fb77e8569be [6.5]
/Users/torarne/dev/qt/6.6/qtbase             a6cb5512c66 [6.6]
/Users/torarne/dev/qt/6.7/qtbase             8d811bb882e [6.7]
/Users/torarne/dev/qt/6.8/qtbase             ae6b6bf363d [6.8]
/Users/torarne/dev/qt/qtbase                 957131c2738 [dev]

# Work on trunk/main development branch `dev`
❯ git branch --show-current                                                                                                                                                                                                                                                                                                                                                                 
dev

❯ git rev-parse --abbrev-ref HEAD@{upstream}
qt-project/dev

❯ git log --pretty=oneline -1
0770171dcda24a567d6f57b87fdd284011e56e16 (HEAD -> dev, qt-project/dev) Docs: uppercase spelling of utf-8

# hack hack hack
❯ git commit -a -m "Add some feature"

# hack hack hack
❯ git commit -a -m "Build on feature added earlier"

# Push feature to Gerrit for review as two individual patches/commits that depend on each other 
❯ git gpush HEAD~2..HEAD --topic my-new-feature +reviwer.a +reviewer.b

# hack hack hack
❯ git commit -a -m "Add a bugfix to something unrelated"

# Push bug fix to Gerrit for review as independent patch/commit, not depending on feature
❯ git gpush HEAD~1..HEAD +reviwer.c

# hack hack hack, add some parts to the original feature I forgot
❯ git revise -a -e HEAD~2

# Update the Gerrit review for the feature with a new patch version of the first commit
❯ git gpush HEAD~3..HEAD~1

# Move to hot fix on 5.15 branch
❯ cd ~/dev/qt/5.15/qtbase
❯ git cherry-pick -x <some commit>

# Push cherry-pick to production branch (upstream 5.15)
❯ git gpush HEAD~1..HEAD

[torarnv]

Ooo, there is! https://git-scm.com/docs/git-notes#Documentation/git-notes.txt-notesrewriteltcommandgt

[Byron]

It does that by specifying extra headers when creating/rewriting a commit:

❯ gix cat @~1
tree 8b02e57750f3cf0bcb76465284addf50a22c0dfc
parent 1c7b5d23cf8a5d71781d967f2e29c6e7c130ce24
author Sebastian Thiel <[email protected]> 1740666291 +0100
committer Sebastian Thiel <[email protected]> 1740682577 +0100
gitbutler-headers-version 2
gitbutler-change-id 375d33ad-898f-4b07-a8db-be6dccd23258

asdf %                                                                                                                                                                                                                                                                                                                                                                     

[torarnv]

Nifty! Do those custom headers survive plain git tooling operating on the commits? Can you add those headers via git porcelain/plumbing or do you need to write the commit object manually?

[Byron]

Nifty! Do those custom headers survive plain git tooling operating on the commits?

I'd think most tooling handles them gracefully, at least all Git commands do. Forges have no problem as well.

Can you add those headers via git porcelain/plumbing or do you need to write the commit object manually?

We use gitoxide to set them before writing commits back, it's about as straightforward as one might expect:

gitbutler/crates/but-core/src/commit.rs

Lines 72 to 74 in 78a1c35

	commit
	.extra_headers
	.extend(Vec::<(BString, BString)>::from(self));

[torarnv]

I'd think most tooling handles them gracefully, at least all Git commands do. Forges have no problem as well.

Nice, then that's even more robust than a git note :)