Feature Request: enhance Git-GUI's Checkout Branch screen

Feature Request: enhance Git-GUI's Checkout Branch screen

[John Medema]

Git gurus, throw this one on your to-do list:

This is a feature request to enhance the Git GUI to make it easier to
checkout non-existing branches that exist upstream. Apologies if this
is not the correct place for feature requests.

Scenario: Upstream repo has 4 branches - master, develop, maint, test.
Local repo has only a master branch. In the command line, to switch to
a local copy of the test branch, it is a simple "git checkout test".
The git command automatically realizes your requested branch doesn't
exist but origin does have a branch named test, so it a) creates a
local branch off of origin/develop, b) sets the appropriate pull link,
and c) sets the appropriate push link. In effect, the git command line
hides the fact that the user doesn't know the branch doesn't exist and
creates it as the user was expecting it to exist as. The Git GUI has
no shortcut like this.

For reference, from the man page for git-checkout:
"If <branch> is not found but there does exist a tracking branch in
exactly one remote (call it <remote>) with a matching name, treat as
equivalent to "git checkout -b <branch> --track <remote>/<branch>".

Currently, in order to checkout a non-existing branch in the GUI you
must go to the Branch Menu, click Create, select the "Tracking Branch"
radio, select the branch, then go back up and name the branch the
exact same name (to ease new user confusion). For a new user who just
wants a copy of the remote branch, it is very unintuitive to create a
new branch.

Fortunately, you already have some explicit warning messages after the
Checkout Branch screen if the user intuitively tries to checkout the
tracking branch, but even then a new user rarely realizes what they
have gotten themselves into. At best, they know that they must find
help (just for trying to checkout a branch).

In order to implement this feature effectively, I suggest that the
Checkout Branch screen be modified in one of two ways (exclusive):

Option A:
Merge the Local and Tracking Branch lists into one box keeping their
entries separate by their full name ("master" and "origin/master"). If
a user selects a remote branch, ask the user whether to create the
local branch or move to the detached HEAD state (current
functionality).

Option B (preferred):
Keep the Local and Tracking Branch lists separate (as they are now),
and keep the Tracking Branch list as-is. However, on the Local Branch
screen, select include the existing branches in normal font but also
include potential local branches based off of the remote in italics
(or greyed-out, or asterisked, etc). Selecting an italicized entry
creates the new branch from the tracking branch, without user
interaction.


Thanks,

John Medema
Systems Administrator
United Drugs, a Subsidiary of AAP (American Associated Pharmacies)
john.medema@uniteddrugs.com
7243 N 16th Street, Phoenix, AZ 85020
Office:  602-678-1179 x126
Fax:  602-639-4631

-- 
HIPAA NOTICE:  It is against United Drugs’ policy to receive or send 
un-encrypted or non-secured email correspondence containing Protected 
Health Information (PHI) as defined by HIPAA law.
 
Please use fax or phone for correspondence containing PHI.

-- 
This email message is for the sole use of the intended recipient(s) and may 
contain confidential and privileged information. Any unauthorized review, 
use, disclosure or distribution is prohibited. If you are not the intended 
recipient, contact the sender by reply email, and destroy all copies of the 
original message. 

Re: Feature Request: enhance Git-GUI's Checkout Branch screen

[David Aguilar]

On Thu, Sep 03, 2015 at 10:08:24AM -0700, John Medema wrote:
> Git gurus, throw this one on your to-do list:
> 
> This is a feature request to enhance the Git GUI to make it easier to
> checkout non-existing branches that exist upstream. Apologies if this
> is not the correct place for feature requests.
> 
> Scenario: Upstream repo has 4 branches - master, develop, maint, test.
> Local repo has only a master branch. In the command line, to switch to
> a local copy of the test branch, it is a simple "git checkout test".
> The git command automatically realizes your requested branch doesn't
> exist but origin does have a branch named test, so it a) creates a
> local branch off of origin/develop, b) sets the appropriate pull link,
> and c) sets the appropriate push link. In effect, the git command line
> hides the fact that the user doesn't know the branch doesn't exist and
> creates it as the user was expecting it to exist as. The Git GUI has
> no shortcut like this.
> 
> For reference, from the man page for git-checkout:
> "If <branch> is not found but there does exist a tracking branch in
> exactly one remote (call it <remote>) with a matching name, treat as
> equivalent to "git checkout -b <branch> --track <remote>/<branch>".
> 
> Currently, in order to checkout a non-existing branch in the GUI you
> must go to the Branch Menu, click Create, select the "Tracking Branch"
> radio, select the branch, then go back up and name the branch the
> exact same name (to ease new user confusion). For a new user who just
> wants a copy of the remote branch, it is very unintuitive to create a
> new branch.
> 
> Fortunately, you already have some explicit warning messages after the
> Checkout Branch screen if the user intuitively tries to checkout the
> tracking branch, but even then a new user rarely realizes what they
> have gotten themselves into. At best, they know that they must find
> help (just for trying to checkout a branch).
> 
> In order to implement this feature effectively, I suggest that the
> Checkout Branch screen be modified in one of two ways (exclusive):
> 
> Option A:
> Merge the Local and Tracking Branch lists into one box keeping their
> entries separate by their full name ("master" and "origin/master"). If
> a user selects a remote branch, ask the user whether to create the
> local branch or move to the detached HEAD state (current
> functionality).
> 
> Option B (preferred):
> Keep the Local and Tracking Branch lists separate (as they are now),
> and keep the Tracking Branch list as-is. However, on the Local Branch
> screen, select include the existing branches in normal font but also
> include potential local branches based off of the remote in italics
> (or greyed-out, or asterisked, etc). Selecting an italicized entry
> creates the new branch from the tracking branch, without user
> interaction.

How about Option C?

What git-cola[1] has done for the longest time is when the
remote branch is selected it strips of the remote part and
automatically fills in the name field with that.  e.g. it fills
in "todo" when "origin/todo" is selected.

Mixing remote branches with pseudo-branches in the UI would
complicate it, so that seems like it could be made simpler.
Italics, asterisks, those are all signs that they shouldn't
be displayed next to each other.

I think the UI is fine as-is.  If it were just tweaked to
automatically fill in that field, like git-cola does, then it
can stay simple and make this use case easier.

If you're looking for other interesting usability things that
could be improved about git-gui, take a look at the
keyboard-driven user interface features in git-cola.  It's
optimized for keyboard-centric use.

[1] https://github.com/git-cola/git-cola
-- 
David

Re: Feature Request: enhance Git-GUI's Checkout Branch screen

[John Medema]

David,

Option C - when you say "[in git-cola] when the remote branch is
selected it strips of the remote part and automatically fills in the
name field with that", are you referring to the Branch Create screen
or the Branch Checkout screen?  Your description matches the Create
screen.  And for what its worth, that description is accurate and I
agree that cola does a good job of making the branch creation process
easy, and the branch creation process would definitely be improved by
your suggestion.

But as the company's unofficial git admin, I get new git users coming
to me frequently for help and the single most frequent new user
mistake is that the users don't know that they need to create a local
branch in the first place.  They assume a clone really means cloning
and that all the branches from upstream have been created locally on a
clone.  The bash users don't even realize they're creating a branch
when the run "git checkout myNewBranch" - they think they're checking
out an existing branch.  The gui users don't have that shortcut
currently; they can only checkout existing local branches or remote
branches as a detached head.  I'm trying to point out here that in
this (single) use case its actually easier to use the command line
than the gui.

Granted, an argument can made that the new users should know what
they're doing before they dive into things like an SCM.  While in
general I agree, there's also something to be said for making things
easier when it does not impact functionality.  For example, git-cola's
Branch Checkout UI allows you to type in the name of a tracked branch
that doesn't exist yet locally.  If you type in "origin/myBranch" you
get a detached head.  If you type in "myBranch", cola will create the
local branch off of origin/myBranch (as you and I would expect).  Of
course, this cola UI can still be improved too - it doesn't show you
that potential branch in the checkout dropdown list, requiring you to
type it in.  And to make matters worse, if you type it in wrong the
branch checkout silently fails and you stay in your starting branch.
But that isn't your problem.

So I'm not a fan of Option C, where the user is still forced to use
Branch Create.  So what do you think of Option D?

For both the GUI and the command line, during Git Clone operation,
after the existing process completes, the clone action also creates
each remote branch locally.  This bypasses all the problems above, and
has the added benefit of making a clone operation more clone-like
(i.e. it makes the local repository exactly like the upstream
repository).  The starting local branch can still use the upstream's
"default branch" setting.  I've never understood why git didn't do
this since its just adding a pointer to a commit (for each branch).
Is it an attempt to prune the old branch clutter when a repo is cloned
from another repo that is itself cloned (i.e. to remove unused
branches from the grandfather repo)?

Option D has the downside that it changes the behavior of more code
(cmdline and gui), which is why I didn't suggest it before.  It also
has the downside of making the branch list longer.  But that's the
nature of cloning; if I copy a full directory of files to a new
directory I expect to get a full set of files.  If I plan on only
using a small subset of files its up to me to remove them after I've
copied them (I'm assuming that I don't know what files/branches I want
beforehand, which is why I'm copying everything).

Sorry if I overloaded your monitor with all these characters, I'm
trying to anticipate responses.  Thanks for your time,


John Medema
Systems Administrator
United Drugs, a Subsidiary of AAP (American Associated Pharmacies)
john.medema@uniteddrugs.com
7243 N 16th Street, Phoenix, AZ 85020
Office:  602-678-1179 x126
Fax:  602-639-4631


On Thu, Sep 3, 2015 at 9:42 PM, David Aguilar <davvid@gmail.com> wrote:
> On Thu, Sep 03, 2015 at 10:08:24AM -0700, John Medema wrote:
>> Git gurus, throw this one on your to-do list:
>>
>> This is a feature request to enhance the Git GUI to make it easier to
>> checkout non-existing branches that exist upstream. Apologies if this
>> is not the correct place for feature requests.
>>
>> Scenario: Upstream repo has 4 branches - master, develop, maint, test.
>> Local repo has only a master branch. In the command line, to switch to
>> a local copy of the test branch, it is a simple "git checkout test".
>> The git command automatically realizes your requested branch doesn't
>> exist but origin does have a branch named test, so it a) creates a
>> local branch off of origin/develop, b) sets the appropriate pull link,
>> and c) sets the appropriate push link. In effect, the git command line
>> hides the fact that the user doesn't know the branch doesn't exist and
>> creates it as the user was expecting it to exist as. The Git GUI has
>> no shortcut like this.
>>
>> For reference, from the man page for git-checkout:
>> "If <branch> is not found but there does exist a tracking branch in
>> exactly one remote (call it <remote>) with a matching name, treat as
>> equivalent to "git checkout -b <branch> --track <remote>/<branch>".
>>
>> Currently, in order to checkout a non-existing branch in the GUI you
>> must go to the Branch Menu, click Create, select the "Tracking Branch"
>> radio, select the branch, then go back up and name the branch the
>> exact same name (to ease new user confusion). For a new user who just
>> wants a copy of the remote branch, it is very unintuitive to create a
>> new branch.
>>
>> Fortunately, you already have some explicit warning messages after the
>> Checkout Branch screen if the user intuitively tries to checkout the
>> tracking branch, but even then a new user rarely realizes what they
>> have gotten themselves into. At best, they know that they must find
>> help (just for trying to checkout a branch).
>>
>> In order to implement this feature effectively, I suggest that the
>> Checkout Branch screen be modified in one of two ways (exclusive):
>>
>> Option A:
>> Merge the Local and Tracking Branch lists into one box keeping their
>> entries separate by their full name ("master" and "origin/master"). If
>> a user selects a remote branch, ask the user whether to create the
>> local branch or move to the detached HEAD state (current
>> functionality).
>>
>> Option B (preferred):
>> Keep the Local and Tracking Branch lists separate (as they are now),
>> and keep the Tracking Branch list as-is. However, on the Local Branch
>> screen, select include the existing branches in normal font but also
>> include potential local branches based off of the remote in italics
>> (or greyed-out, or asterisked, etc). Selecting an italicized entry
>> creates the new branch from the tracking branch, without user
>> interaction.
>
> How about Option C?
>
> What git-cola[1] has done for the longest time is when the
> remote branch is selected it strips of the remote part and
> automatically fills in the name field with that.  e.g. it fills
> in "todo" when "origin/todo" is selected.
>
> Mixing remote branches with pseudo-branches in the UI would
> complicate it, so that seems like it could be made simpler.
> Italics, asterisks, those are all signs that they shouldn't
> be displayed next to each other.
>
> I think the UI is fine as-is.  If it were just tweaked to
> automatically fill in that field, like git-cola does, then it
> can stay simple and make this use case easier.
>
> If you're looking for other interesting usability things that
> could be improved about git-gui, take a look at the
> keyboard-driven user interface features in git-cola.  It's
> optimized for keyboard-centric use.
>
> [1] https://github.com/git-cola/git-cola
> --
> David

-- 
HIPAA NOTICE:  It is against United Drugs’ policy to receive or send 
un-encrypted or non-secured email correspondence containing Protected 
Health Information (PHI) as defined by HIPAA law.
 
Please use fax or phone for correspondence containing PHI.

-- 
This email message is for the sole use of the intended recipient(s) and may 
contain confidential and privileged information. Any unauthorized review, 
use, disclosure or distribution is prohibited. If you are not the intended 
recipient, contact the sender by reply email, and destroy all copies of the 
original message. 

Re: Feature Request: enhance Git-GUI's Checkout Branch screen

[Junio C Hamano]

John Medema <john.medema@uniteddrugs.com> writes:

> Option D has the downside that it changes the behavior of more code
> (cmdline and gui), which is why I didn't suggest it before.  It also
> has the downside of making the branch list longer.  But that's the
> nature of cloning; if I copy a full directory of files to a new
> directory I expect to get a full set of files.

You shouldn't be too literal with the word "clone".  The reason
people "clone" a project often is to work on their own thing, which
may be based only on a handful of branches the upstream publishes.

So I do necessarily buy "But that's the nature" argument myself.

Not doing your option D has another benefit, other than "smaller
number of branches" you mentioned, and it is more important one in
practice.  Once you start your own development with your own set of
branches, you want to see the names of _your_ branches in your
repository, not mixed with 47 other uninteresting branches your
upstream has for its purpose.  Whey you are working on fixing
something for the maintenance track of the upstream, you do want to
see your 'fix-that-thing' local branch forked from 'maint' branch of
the upstream, and you may or may not also want to see a copy of
'maint' branch in your local branch namespace, but you certainly do
not want to see 'master', 'next', 'pu' and all the topic branches
the upstream uses to build and advance these branches ahead of
'maint' that you are currently focusing on.

In fact, with ancient versions of Git, you got copies of all
branches your upstream has as your local branches.  This turned to
be unusable and was corrected at around v1.5.0 release---this was
done primarily so that we can have a sane remote-tracking, but
uncluttering the local branch space was also a reason why we
transitioned to the current "separate remote" layout.

Re: Feature Request: enhance Git-GUI's Checkout Branch screen

[John Medema]

Junio,

I can appreciate the amount of clutter you'd get with the ancient
behavior.  That said, I'd be willing to live with it.  I personally
prefer to see all the branches coming and going - if the branches are
good enough for upstream, they're good enough for me (I'm really good
an ignoring stuff).

Realizing I'm probably not in the majority, I'd think that re-enabling
this ancient behavior as a non-default option (like git config
push.default) might be nice for those of my inclination.  As of now I
need to write a script to do a fetch + create_branch( diff( local vs
origin ) ).

But like I said before, I was hoping I'd have an easier time
convincing you guys on Options A or B to make the gui more consistent
with the cmdline.

Thanks,

John Medema
Systems Administrator
United Drugs, a Subsidiary of AAP (American Associated Pharmacies)
john.medema@uniteddrugs.com
7243 N 16th Street, Phoenix, AZ 85020
Office:  602-678-1179 x126
Fax:  602-639-4631


On Fri, Sep 4, 2015 at 3:16 PM, Junio C Hamano <gitster@pobox.com> wrote:
> John Medema <john.medema@uniteddrugs.com> writes:
>
>> Option D has the downside that it changes the behavior of more code
>> (cmdline and gui), which is why I didn't suggest it before.  It also
>> has the downside of making the branch list longer.  But that's the
>> nature of cloning; if I copy a full directory of files to a new
>> directory I expect to get a full set of files.
>
> You shouldn't be too literal with the word "clone".  The reason
> people "clone" a project often is to work on their own thing, which
> may be based only on a handful of branches the upstream publishes.
>
> So I do necessarily buy "But that's the nature" argument myself.
>
> Not doing your option D has another benefit, other than "smaller
> number of branches" you mentioned, and it is more important one in
> practice.  Once you start your own development with your own set of
> branches, you want to see the names of _your_ branches in your
> repository, not mixed with 47 other uninteresting branches your
> upstream has for its purpose.  Whey you are working on fixing
> something for the maintenance track of the upstream, you do want to
> see your 'fix-that-thing' local branch forked from 'maint' branch of
> the upstream, and you may or may not also want to see a copy of
> 'maint' branch in your local branch namespace, but you certainly do
> not want to see 'master', 'next', 'pu' and all the topic branches
> the upstream uses to build and advance these branches ahead of
> 'maint' that you are currently focusing on.
>
> In fact, with ancient versions of Git, you got copies of all
> branches your upstream has as your local branches.  This turned to
> be unusable and was corrected at around v1.5.0 release---this was
> done primarily so that we can have a sane remote-tracking, but
> uncluttering the local branch space was also a reason why we
> transitioned to the current "separate remote" layout.

-- 
HIPAA NOTICE:  It is against United Drugs’ policy to receive or send 
un-encrypted or non-secured email correspondence containing Protected 
Health Information (PHI) as defined by HIPAA law.
 
Please use fax or phone for correspondence containing PHI.

-- 
This email message is for the sole use of the intended recipient(s) and may 
contain confidential and privileged information. Any unauthorized review, 
use, disclosure or distribution is prohibited. If you are not the intended 
recipient, contact the sender by reply email, and destroy all copies of the 
original message.