cli: tab-complete branch names in shell

[incidentist]

For commands that accept branch names, it would be very useful to have shell completions for branch names, similar to git. Example: but move my-ex<tab> becomes but move my-extremely-long-and-unwieldly-branch-name.

[Byron]

Thanks a lot for sharing.

For what I know, in order to accomplish this one would have to ship a separate program that performs the dynamic completions accordingly. Here is more information on how to achieve that with clap: https://deepwiki.com/clap-rs/clap/6.2-dynamic-completions .

[slarse]

Hi @incidentist!

This is on the roadmap and will absolutely be added, it just isn't very high up on the priority list at the moment as the vast majority of commands take short IDs that hardly need completion. With your example of but move, instead of actually typing out the extremely long branch name you could use its short ID which is written out to the left of the full name:

$ but status
╭┄zz [uncommitted] (no changes)
┊
┊╭┄my [my-extremely-long-and-unwieldly-branch-name]
┊●   83955cb Some commit (no changes)
├╯
┊
┊╭┄ot [other-extremely-long-and-unwieldly-branch-name]
┊●   57f5b18 Other commit (no changes)
├╯
┊
┴ ee6bd93 (common base) 2026-06-29 Initial empty commit

Hint: run `but help` for all commands

$ but move my ot
Moved branch my-extremely-long-and-unwieldly-branch-name on top of other-extremely-long-and-unwieldly-branch-name.
[playground]$ but status
╭┄zz [uncommitted] (no changes)
┊
┊╭┄my [my-extremely-long-and-unwieldly-branch-name]
┊●   d9f151b Some commit (no changes)
┊│
┊├┄ot [other-extremely-long-and-unwieldly-branch-name]
┊●   57f5b18 Other commit (no changes)
├╯
┊
┴ ee6bd93 (common base) 2026-06-29 Initial empty commit

Hint: run `but help` for all commands

The only real pain point I personally have right now is with but apply, which requires full-length branch names. Other than that short IDs almost completely obviate the need for dynamic completions. That being said, we'll still want to add them in the not too distant future, but there are quite a few performance considerations to take into account when it comes to adding dynamic completions in but, so it's not something we'll just do off the cuff. It requires some amount of care, which is why we're delaying it a little bit at the moment.

[incidentist]

Thanks! I often use short IDs, but that usually requires running but before the command to know what the short IDs are. For commands that take branches, I usually know what the branch name is and tab-completing it is faster than running but to get the short ID and using that. (in this case, I was trying to move a branch that hadn't been applied, which doesn't actually work but I'd love it if it did, but that's a separate issue :P )

For the record, my current vibecoded fish workaround is this in ~/.config/fish/functions/__fish_but_branches.fish:

function __fish_but_branches --description 'List GitButler branch names for completion'
    but --format json branch list --local --all --no-check --no-ahead 2>/dev/null \
        | jq -r '.appliedStacks[].heads[].name, .branches[].name' 2>/dev/null
end

and this in ~/.config/fish/conf.d/gitbutler.fish:

# GitButler setup
but completions fish | source

# Dynamic branch-name completion (but completions fish has no branch lookup, see
# https://github.com/gitbutlerapp/gitbutler)
complete -c but -n "__fish_but_using_subcommand switch" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand apply" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand unapply" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand merge" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand pick" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand move" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand rub" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand show" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand squash" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand push" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand reword" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand absorb" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand commit; and not __fish_seen_subcommand_from empty" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand stage" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand stage" -s b -l branch -r -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand branch; and __fish_seen_subcommand_from delete" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand branch; and __fish_seen_subcommand_from show" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand branch; and __fish_seen_subcommand_from update" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand branch; and __fish_seen_subcommand_from new" -s a -l anchor -r -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand pr; and __fish_seen_subcommand_from new" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand review; and __fish_seen_subcommand_from new" -f -a "(__fish_but_branches)"
complete -c but -n "__fish_but_using_subcommand mr; and __fish_seen_subcommand_from new" -f -a "(__fish_but_branches)"

[curtisault]

I presume that if this is added to the CLI, it will also be added to the TUI?

[Byron]

@curtisault TUI and CLI are separate in regards of completion, and assuming the question is related to running but commands from the TUI, then completions definitely wouldn't be available either. Pinging @davidpdrsn to see if anything is planned in this regard.