What is the proper CLI workflow? Why does commit not automatically pick up (just) staged files?

[gwkunze]

With git I generally do something like:

1. Make a branch and switch to it git checkout -b my-branch
2. Do some work
3. Stage files with git add
4. run git commit
5. run git push my-branch

I've been using GitButler CLI for a while now and I do:

1. Make a branch but branch new my-branch
2. Do some work
3. Stage files with but stage (interactive, select branch and files/hunks to stage)
4. Commit with but commit my-branch -o
5. Push with but push (interactive, select branch(es) to push)

This all works, but it feels slightly wonky to me. but stage stages file for commit and it seems you can only stage for one branch at a time if you have multiple active branches as if you but stage something else it discards any uncommitted previous stages (although you can have multiple staged files in different branches via the rub command, but that feels like hacking your way into a potentially undesired state). Presuming the only one staged branch at a time semantics, why must I specify a branch name AND -o when running but commit, surely if something is explicitly staged, that is what the user wants to commit?

I tend to have to work on multiple things at the same time so GitButler's way of having multiple active branches is great for me, and so far I've really enjoyed many of the features GitButler provides. However with my way of working I rarely want to commit all current changes to the same branch so the default of but commit' committing everything to the selected branch is (to me) somewhat unintuitive, rarely desired and feels like it makes staging feel practically useless.

I can understand defaulting to committing all unstaged files when nothing is staged, but doing so when things are staged has bitten me a couple of times already. And maybe this is just me still being on Git-brain instead of GitButler-brain, so if there is an improvement to my way of working I'll be glad to hear it. Thanks.

[VectorPeak]

Your read is reasonable: this isn’t just “Git-brain”. In GitButler, stage is closer to “assign these changes/hunks to this branch” than Git’s single global index. commit is branch-oriented, so by default it tries to make a commit for the selected branch from the branch’s current change set, and --only narrows that to the explicitly staged/assigned changes.

For the workflow you described, the safer pattern is:

but branch new my-branch
but stage --branch my-branch
but commit --only my-branch
but push

or, with a message:

but commit --only -m "My commit message" my-branch

The surprising part is exactly what you called out: once you have explicitly staged changes, that is a strong signal of intent. Having but commit my-branch also sweep in other changes can be dangerous in a multi-active-branch workflow, especially for people using GitButler specifically to split unrelated work apart.

The current behavior is mostly optimized for the “commit everything currently assigned to this branch” flow, but the CLI could probably make this clearer or safer. A few possible improvements would be: default to staged-only when staged changes exist, warn before including unstaged/unassigned changes, or add a config option for Git-style commit semantics.

rub is not meant to be a hack, but it is definitely more of a power-user/general editing primitive than the happy-path commit workflow. For day-to-day use, but stage ... followed by but commit --only ... is the workflow that best matches what you’re trying to do today.

---

If my answer solved your problem, you can click answered the question. I'm really here to help, and along the way I'm also collecting Galaxy Brain badges haha 😆

[Byron]

Thanks for sharing!

To me, it feels like the butt CLI isn't very well tuned right now, especially if staging is involved, and I'd think this will change. Here there is a bit of a split-brain going on where but has to ignore the Git index, as each tip of a branch is a staging area, but but commit currently easily ignores it by default. There is a new implementation of commit coming up which might be more intuitive here, @davidpdrsn will know more about this.
I wouldn't be surprised if a new stage implementation is also on the way.

This isn't a satisfactory answer as there is a lot of guessing involved, but I hope when David chimes in it will all become clearer.

[veber-alex]

I am also getting the feeling that stage is practically useless in gitbutler.

Can anyone elaborate on how to use it correctly? The user guide gives the mechanical details but doesn't really explain what it is for.

So far, every time I wanted to "stage" something I just committed it. Am I missing something here? What is the added value?

[davidpdrsn]

There is an ongoing internal discussion about the future of staging in GitButler. So while I cannot say anything for certain, I think it is very likely that staging as a feature will be removed from the products. This includes the CLI, the TUI, and our new in-development Electron-based GUI. It likely wont be removed from the Tauri app because the Electron version is the future.

The idea is that if it's easy to pick what and where to commit, and the commits are easy to change after the fact, then there isn't a need for staging. It becomes an unnecessary holdover from how the git CLI expects you to work. You can just commit some changes to one branch and some other changes to another branch. There is no need to first stage and then commit. You can later massage the commits (squash/move/reword/etc.) to get them ready for review.

The new commands that @Byron hint at are being designed with this in mind. They will not support staging.

Personally, my workflow is to make lots of small "work-in-progress" commits to my parallel branches and then squash them into one commit per branch before opening a PR. Sometimes I also start with one empty commit per branch that I keep amending with new changes. It depends on the day.