Improve branch management

[smashwilson]

Our current BranchMenuView tooltip control has a few major limitations:

• It's unusable with large numbers of branches.
• It shows only local branches. (#302)
• It makes it easy to create branches from the wrong starting commit.

I'd like to start a discussion about what to replace it with and what capabilities we want it to support. There's a balance to strike between overwhelming users with a panel that has a million checkboxes on it, but providing enough functionality to keep people from context-switching to the commandline as much as possible.

Here are a few ideas about features we might like to support:

• Filtering and searching large branch lists.
• Deleting branches.
• Renaming branches.
• Checking out a local branch that tracks a remote tracking branch.
• Initiating a merge or a non-interactive rebase.

@simurai already has some mockups to consider in other issues: https://github.com/atom/github/issues/302#issuecomment-279124372, #311.

[simurai]

Looking at #302 + #311 with a long list doesn't seem such a good idea anymore:

Tooltip	Top bar

Often that tooltip/dropdown will going from top to bottom. Or we have some max-height, but that might feel frustrating on a larger monitor. Also, you would've to be very carful to not loose focus and accidentally close the tooltip/dropdown. Less a problem for simple branch switching, but if we want to add more management features, it would be good to not have to worry about loosing focus.

TL;DR: Should we move branch management back to a side panel? Not part of the current commit panel like it used to be, but into its own panel. This proposal seems very timely too.

[simurai]

Here branches in a panel:

• Initial scroll position is so that the current branch is at the top
• Filter branches by typing the branch name
• Maybe even offer other filter options, like "sort:new" or "sort:date" would temporarily sort the branches by newest first.
• If there is no matching branch, the create button is active and clicking it creates a new branch (based on your current branch)
• Dot (on the left): this is an indicator for the currently checked out branch
• Circle (on the left): this is an indicator for branches that are tracking a remote branch
• You can see if commits are ahead and/or behind (2|0)
• Shield icon shows the default branch

Context menu

Most actions are available in a context menu, some that come to mind (and not in a particular order):

• Headers ("Local branches", "origin", "another-remote")
  • [Fetch] Not sure what will happen with the Fetch/Pull/Push tooltip, but we could still offer to fetch here too.
  • [Delete merged branches] this is a way to easily clean up your local branches and delete the ones that got merged. So instead of deleting one by one and having to think if you still need a branch, you can just use this once in awhile. Not sure if it's also possible for remotes or if we even should. At least offer a [Prune branches] that will remove all branches that got deleted on the remote. Could also be called "update" or "refresh"?
• Branches
  • [Checkout] will checkout a branch. If it's a remote branch it will also track it.
  • [Merge] will merge onto your current branch
  • [Rebase] will rebase onto your current branch
  • [Create branch] will create a new branch based on the selected one. Maybe for remote branches even track and do a checkout since you most likely wanna do that too. The text input at the top can be re-used and even pre-populated with the same branch name. So it's easy to create a variation and you don't have to retype the name. branch-name -> branch-name2.
  • [Track] will track a branch. This is mostly needed when you want to switch tracking between remotes. You can also [Untrack] if a branch already is tracking another one. Maybe to prevent accidental pushes.
  • [Pull/Push] same as with fetch, just another place to do it. Handy when you see that commits are ahead | behind and you can pull/push right there.
  • [Rename] replaces the branch name with a text input.
  • [Delete] Deletes the branch. If a local branch has unmerged commits, maybe show a warning/notification.

As always, this is just "where things could go ™" and can be done in multiple steps.

Also /cc @donokuda that has a secret thing for branch UIs.

[simurai]

Some more questions:

What happens if you click on a branch with the mouse? Does it do a checkout or just select the branch? Probably the later. At some point we might want to show the commit history when selecting a branch. To do a checkout without using the context menu, you could double-click, like when staging/unstaging.

Also, how do you open the context menu with the keyboard if you want to do anything other than a checkout? On macOS you could enable it but it's not on by default.

Then I guess we also need a way to manage the remotes? Like adding, renaming, deleting.

[winstliu]

This looks awesome! My only concern is that the shield icon could get mistaken for protected branches.

[thomasjo]

My only concern is that the shield icon could get mistaken for protected branches.

Yeah, I agree. What about using (home) or perhaps one of these?

[smashwilson]

:heart: I love the direction this is going in!

Some thoughts on specific bits:

Circle (on the left): this is an indicator for branches that are tracking a remote branch

This one isn't obvious to me. The behind/ahead indicator already marks a branch as tracking; do we need a different indication? I think it also collides with the dot-for-current element; my brain keeps wanting the two elements to be related.

[Delete merged branches]

:+1: I have a git-delete-merged script to do this on the command-line now.

Would this make more sense as a context menu option on a specific branch, though? Then it becomes "delete branches merged into branch X" which feels less ambiguous to me.

We'd also likely want either some kind of confirmation about which branches you're about to delete or an easy undo.

[Rebase]

This would make more sense to me as "rebase your current branch onto the selected branch."

[Create branch] [..] Maybe for remote branches even track and do a checkout since you most likely wanna do that too.

:+1: :sparkles: Definitely.

[Pull/Push]

Does this make sense for branches that aren't currently checked out? I think Push can work, but Pull requires a working copy to handle any possible merges. We could automagically stash/checkout/pull/checkout old/stash pop but offhand I'd think there are too many things that could go wrong in those intermediate stages and leave your repository in odd states without enough indication of how you got there.

Does it do a checkout or just select the branch? Probably the later. At some point we might want to show the commit history when selecting a branch. To do a checkout without using the context menu, you could double-click, like when staging/unstaging.

:+1: for just selecting the branch and checking out on double-click.

Then I guess we also need a way to manage the remotes? Like adding, renaming, deleting.

See #555! Ideally we could integrate the two: from the branch view, navigate to the remote management UI with a specific remote focused, and from the remote view, navigate to the branch view with a specific remote focused.

Overall

• How would you feel about promoting this to its own full PaneItem rather than just a tab in the panel? .com gives branches their own full page which is pretty nice. Maybe we could use the extra space to show more branch information (last commit message snippet, avatar, timestamp?) and some explicit controls for some of the context menu actions. Not :100: pushing for this, just a thought.
• Could we add some kind of decoration or icon to highlight the tracking branch of the current branch? Maybe it's too obvious in the common case where they share a name.
• Maybe add a "tags" group like the remote groups? I'm not sure where a "create tag" action belongs.

[simurai]

@50Wliu My only concern is that the shield icon could get mistaken for protected branches.

Oh.. you're right. I just looked at https://github.com/atom/github/branches and didn't realize that the default branch is also protected. So yeah, we could have both:

• Default label or another icon for the default branch
• 🛡 Shield icon for protected branches. Might be handy to know since you can't force push to those.

[simurai]

@simurai Circle (on the left): this is an indicator for branches that are tracking a remote branch @smashwilson This one isn't obvious to me. The behind/ahead indicator already marks a branch as tracking; do we need a different indication? I think it also collides with the dot-for-current element; my brain keeps wanting the two elements to be related.

Ya, I'm also not too convinced about that. My intention was to find a way to show which of the remotes a local branch is tracking. This is to prevent the "why do my commits not show up... ohh.. I pushed to my personal fork :triumph:". It might be more clear when forks use a different color:

Hmm.. maybe too much 🎄

Writing out the full path would also be possible: another-remote/some-experiment. But then there are space/truncation concerns.

Here just checkmarks for the current branch. And a tooltip when hovering the ahead|behind counter:

[simurai]

[Delete merged branches] 👍 I have a git-delete-merged script to do this on the command-line now. Would this make more sense as a context menu option on a specific branch, though? Then it becomes "delete branches merged into branch X" which feels less ambiguous to me.

Isn't that a lot of work having to got through all branches to figure out which branch has unmerged commits? Yeah, maybe we could give a preview first. Like the context menu would say "Show branches where all commits commits got merged". Then you can see them first before you "select all" and delete them for good.

[Rebase] This would make more sense to me as "rebase your current branch onto the selected branch."

Would the selected branch be checked out afterwards? As far as I understand this all, you only can "receive" so that you can handle potential merge conflicts. Or would it checkout selected branch -> rebase -> checkout previous branch (without you noticing). So then it would feel like "giving" your commits to the selected branch.

How would you feel about promoting this to its own full PaneItem rather than just a tab in the panel? .com gives branches their own full page which is pretty nice. Maybe we could use the extra space to show more branch information (last commit message snippet, avatar, timestamp?) and some explicit controls for some of the context menu actions. Not 💯 pushing for this, just a thought.

🤔 The additional space sounds nice, but maybe a bit overkill when just switching branches or creating a new one?

Another idea to see "last commit message snippet, avatar, timestamp?".. well, kinda depends on how https://github.com/atom/atom/issues/13878 pans out:

"Link" the branch panel with a history panel. Then if you split panes and have them side by side you can select a branch and see its commits. And selecting a commit would show the diff for that commit. Then at any time you can check out what's happening on other branches without having to check them out first. Or you can cherry pick a commit into your current branch. Anyways, let's not drift off too far and stay on topic. 😇

Could we add some kind of decoration or icon to highlight the tracking branch of the current branch? Maybe it's too obvious in the common case where they share a name.

Would the two checkmarks in https://github.com/atom/github/issues/556#issuecomment-283852568 help? Could also be a link 🔗 icon. Then even if the names are differnt, you still see which remote branch is being tracked.

Maybe add a "tags" group like the remote groups? I'm not sure where a "create tag" action belongs.

Yeah, could be another group. To create a tag, you need to tell the exact commit, right? Maybe wait until there is a history view so you can tag from there.

[simurai]

How would you feel about promoting this to its own full PaneItem

Ok, at least somebody would appreciate the extra space 👇 :

btw. would it be possible to keep the current tooltip in addition to a new panel/pane with all the management options? Maybe not forever but just to see how its usage changes when we would have both. One reason I like the tooltip is because it auto-closes (when focusing away) and it feels like less work. Be able to close the panel with esc might be fine to.. like find+replace, a quick in-n-out.

[cbovis]

@simurai the dots and ticks feel confusing to me personally. The dots feel like radio buttons and the ticks feel like a selected state. The Git Plus package actually uses ticks in their Cherry Pick interface to signify which commits you've picked.

I like what the Tower git client does with regards to indicating the HEAD and upstream/downstream changes...

Absolutely love the idea of the contextual panel you mocked up for history. I could see this being used elsewhere for stashes with the main panel listing the stashes and the contextual panel displaying the changes for a particular stash.

[surdu]

One small improvement on the current implementation of New Branch, that might get carried into the next version as well is to have the last branch name you've previously created filled in the branch name and pre-selected.

My use-case is when you work with a git-flow-like style of branching, and you have to create branches like feature/.... Having the text there, it's easy just to use the arrows to get rid of the text pre-selection and modify the branch name instead of typing it all from the beginning.

If you don't need the previous branch name, having the text pre-selected in the input allows you to just start typing the new name and the new name should override the old one.

If this is something that you guys find desireable, I could try to work on it myself.

[simurai]

@surdu have the last branch name you've previously created filled in the branch name and pre-selected.

👍 That's a great idea. Maybe one small concern: It then might feel like you're branching off from your previous branch and not the one that you are currently on (and showing in the status-bar).

So instead we could do something similar to find-and-replace. There you can hit the ⬆️ key to cycle through your previous searches.

We could still prefill the branch name but it might be safer to only prefill with your current branch name. For example if your current branch is feature/branch-management and you click on "New Branch", you probably want to create an alternative like feature/branch-management-alternative. Not having to type the beginning would be super handy.

And when you're on master, then keep it empty since the branch name could be anything.

[surdu]

@simurai We could still prefill the branch name but it might be safer to only prefill with your current branch name.

When I create feature branches I usually create them from develop/master not from another feature branch. I might be wrong, but so should be all the other people that follow a git-flow strategy. So filling the input with the branch name might be as useful as leaving it empty for these people.

The up arrow key is a great idea, but has the downside that might not be intuitive for the users that they can do that. That being said, I and many others have discovered that you have a history in find-and-replace input and it's not hinted in any way.

[hamza]

Not sure if this is out of scope for this, or if it already exists (can't find it if it does), but it would be great to add keystroke bindable commands for branch related stuff, something like

github:switch-branch github:new-branch

etc. Similar to what you find in the GitHub desktop app.

[calebmeyer]

I came to atom from spacemacs, and a nice keyboard based workflow for branching is something I've been sorely missing.

In spacemacs, you get to the git status panel (magit-status) with space g s, and from there you have keyboard commands for pushing, pulling, fetching, checking out, branching, etc. (this is due to emacs not always being in a mouse environment)

One of the things that confused me at first about their branching is you're required to always select a starting branch (it doesn't assume your current branch like git branch does). That's something we can definitely improve on. For a mouse based workflow, you can do the right click > checkout. For a keyboard based workflow, maybe we have a dropdown pre-populated with the current branch that can be shift-tabbed to? I'm not good at mockups, but I'll attempt an ascii art one:

Git: Checkout New Branch

  Base Branch
+--------------------------+
|  current-branch-name   v |
+--------------------------+

  New Branch
+--------------------------+
|  |                       |
+--------------------------+

Here the new branch input is a standard text input and has keyboard focus, and the base branch is a dropdown that supports searching with the keyboard.

[ambischof]

For the issue of too many branches, I think a big help would be to sort the branches by last committed to. In my local setup I typically do git branch --sort=-committerdate so the recent branches are on top. I'm also a fan of --no-merged flag