The git spring cleanup challenge completion

The git spring cleanup challenge completion

[Felipe Contreras]

Hello,

One month ago I suggested the git spring cleanup challenge [1], which
after 50 replies can probably be considered a success.

After one month of trying my best not to add many configurations, this
is my final .gitconfig:

  [merge]
    conflictstyle = diff3
  [alias]
    co = commit -v -s
    br = branch

Judging from the discussion, diff3 should definitely become the new
default conflict style. I already sent some patches [2] to try to start
moving in that direction, but unfortunately it doesn't seem to be that
easy because many commands simply ignore that configuration, while
others have issues with the configuration and the command line. Many
probably need a new command line argument to specify the desired
conflict style. A lot of work is needed.

Not to mention the two new proposals to have a new, better diff3: zdiff3
[3] [4]. These come from a proposal from Uwe Kleine-König in 2013 [5].


Other than that, it's fair to say that *everyone* needs some command
aliases to use git. This past month shell completions have saved me, but
not completely. I can't imagine how a newcomer must feel using git
without any alias.

I sent some patches to attempt to have some standard default aliases
[6], also, there's this old thread where default aliases were discussed
at depth [7].

Another uncontroversial configuration everyone agrees should be the
default is `rerere.enabled`. Although `rerere.autoupdate` is more
controversial, I don't see why it cannot be considered too.

Here's a few other interesting configurations:

  * rebase.autosquash = true
  * rebase.autostash = true 
  * commit.verbose = true
  * diff.colorMoved = true
  * grep.patternType = perl
  * alias.undo = reset --hard @{1}
  * feature.experimental = true
  * branch.sort = committerdate
  * diff.algorithm = histogram

I for one can't wait to finally have proper aliases again.

That was painful.

Cheers.

[1] https://lore.kernel.org/git/60b5d281552d6_e359f20828@natae.notmuch/
[2] https://lore.kernel.org/git/20210622002714.1720891-1-felipe.contreras@gmail.com/
[3] https://lore.kernel.org/git/20210613143155.836591-1-felipe.contreras@gmail.com/
[4] https://lore.kernel.org/git/b7561a67c192d4bdede47fee5b7b1cb30c44b785.1623734171.git.gitgitgadget@gmail.com/
[5] https://lore.kernel.org/git/1362602202-29749-1-git-send-email-u.kleine-koenig@pengutronix.de/
[6] https://lore.kernel.org/git/20210702100506.1422429-1-felipe.contreras@gmail.com/T/#t
[7] https://lore.kernel.org/git/CAMP44s17h4Tjg+VaMF0atLep8t-0HVp4UDr1WE2wYnEuZ07eaQ@mail.gmail.com/

-- 
Felipe Contreras

Re: The git spring cleanup challenge completion

[Bagas Sanjaya]

On 03/07/21 05.49, Felipe Contreras wrote:
> Other than that, it's fair to say that *everyone* needs some command
> aliases to use git. This past month shell completions have saved me, but
> not completely. I can't imagine how a newcomer must feel using git
> without any alias.

I personally use git *sans* aliases. I prefer writing full commands 
(like `git checkout`) rather than shorter aliases (like `git co`) so 
that I know what my intentions are.

-- 
An old man doll... just what I always wanted! - Clara

Re: The git spring cleanup challenge completion

[Atharva Raykar]

On 03-Jul-2021, at 04:19, Felipe Contreras <felipe.contreras@gmail.com> wrote:
> 
> [...]
> Other than that, it's fair to say that *everyone* needs some command
> aliases to use git. This past month shell completions have saved me, but
> not completely. I can't imagine how a newcomer must feel using git
> without any alias.

TLDR: I don't think young, first-time learners of Git would mind the lack
of aliases. I cannot speak for people coming from other VCS's.

------ Long Version -------

Hi, maybe I can help bring some perspective on how newcomers view and use
Git. I help run an Open Source club in my University, and one of the first
things we help a lot of new contributors with is teaching Git.

I have conducted multiple workshops over the last two years, so I have
some idea of what the usual struggles and pain points are. I also have
some recollection of what it's like being a new user.

Most of these new users have never used any kind of VCS before, so half
the problem is the overload of all these new concepts of branches,
checking out, staging area, committing, pushing, pulling, etc.

Users are not able to properly map the name of these commands with what
it actually does. Most of the issues stem from trying to memorise these
commands as a series of mantras and applying them without knowing what
is actually happening.

Users are confused about why there is an "add", and then a "commit".
It seems conceptually similar to them. The difference between reset,
restore, revert (and even rebase) is also a pain point, because those
words sound very similar.

Combine the lack of understanding of what Git is actually doing, with the
fear of losing work, and you get the perfect storm of a difficult
experience.

For most new users Git is unusable, unless you explain to them the right
mental model of Git being a graph of immutable commit objects with
pointers to access their contents. In my opinion, trying to make this
model more transparent to a new user is the best way to improve their
experience.

What new users do not have a problem with is a lack of aliases, because
they carry no previous expectation from other VCS's, as Git is always their
first one. I can imagine aliases like 'co' only adding to the overload of
information if an instructor is not careful. FWIW, I have never seen a new
user complain about the length of the typing, it's usually with the plethora
of unintelligible (to them) options that each command has when they open the
Git man pages, which adds more fear.

I do not have an opinion about default aliases, I only had a narrow point,
ie, on the list of impactful things that helps Git newcomers around my
circles, aliases would not score very high. Those who love the command
line among the more enthusiastic learners will set those aliases themselves
anyway.

---
Atharva Raykar
ಅಥರ್ವ ರಾಯ್ಕರ್
अथर्व रायकर

Re: The git spring cleanup challenge completion

[Felipe Contreras]

Bagas Sanjaya wrote:
> On 03/07/21 05.49, Felipe Contreras wrote:
> > Other than that, it's fair to say that *everyone* needs some command
> > aliases to use git. This past month shell completions have saved me, but
> > not completely. I can't imagine how a newcomer must feel using git
> > without any alias.
> 
> I personally use git *sans* aliases. I prefer writing full commands 
> (like `git checkout`) rather than shorter aliases (like `git co`) so 
> that I know what my intentions are.

OK. Virtually everyone.

Have you tried aliases? I just went through a month of getting outside
my confort zone.

-- 
Felipe Contreras

Re: The git spring cleanup challenge completion

[Felipe Contreras]

Atharva Raykar wrote:
> On 03-Jul-2021, at 04:19, Felipe Contreras <felipe.contreras@gmail.com> wrote:
> > 
> > [...]
> > Other than that, it's fair to say that *everyone* needs some command
> > aliases to use git. This past month shell completions have saved me, but
> > not completely. I can't imagine how a newcomer must feel using git
> > without any alias.
> 
> TLDR: I don't think young, first-time learners of Git would mind the lack
> of aliases. I cannot speak for people coming from other VCS's.

That's not the same thing. Of course a user wouldn't mind the lack of
certain feature if he doesn't know he is missing that feature in the
first place.

Humans went for thousands of years using luggage without wheels, does
that mean they "didn't mind" luggage without wheels? They had nothing to
compare it to, so they of course didn't complain, but that doesn't mean
they were "fine".

In order for them to know if they mind it or not they would first need
to try them.

> ------ Long Version -------
> 
> Hi, maybe I can help bring some perspective on how newcomers view and use
> Git. I help run an Open Source club in my University, and one of the first
> things we help a lot of new contributors with is teaching Git.
> 
> I have conducted multiple workshops over the last two years, so I have
> some idea of what the usual struggles and pain points are. I also have
> some recollection of what it's like being a new user.
> 
> Most of these new users have never used any kind of VCS before, so half
> the problem is the overload of all these new concepts of branches,
> checking out, staging area, committing, pushing, pulling, etc.

Sure, that's understandable.

> Users are not able to properly map the name of these commands with what
> it actually does. Most of the issues stem from trying to memorise these
> commands as a series of mantras and applying them without knowing what
> is actually happening.

I recall using git that way a long time ago.

> Users are confused about why there is an "add", and then a "commit".
> It seems conceptually similar to them. The difference between reset,
> restore, revert (and even rebase) is also a pain point, because those
> words sound very similar.

Yeap, I remember that.

> Combine the lack of understanding of what Git is actually doing, with the
> fear of losing work, and you get the perfect storm of a difficult
> experience.
> 
> For most new users Git is unusable, unless you explain to them the right
> mental model of Git being a graph of immutable commit objects with
> pointers to access their contents. In my opinion, trying to make this
> model more transparent to a new user is the best way to improve their
> experience.

Sure, I see those pain points, and I have sent plenty of patches to
improve that experience, but none of them have been applied.

> What new users do not have a problem with is a lack of aliases, because
> they carry no previous expectation from other VCS's, as Git is always their
> first one.

Sure, when they are learning git they don't need aliases, but after they
become fluent and can do some basic workflow without looking to cheat
sheets they *immediately* would benefit from them.

> I can imagine aliases like 'co' only adding to the overload of
> information if an instructor is not careful. FWIW, I have never seen a new
> user complain about the length of the typing, it's usually with the plethora
> of unintelligible (to them) options that each command has when they open the
> Git man pages, which adds more fear.

This is one of the reasons I suggested to split git into two binaries:
git for normal users, and git-tool for all the plumbing not many humans
use.

> I do not have an opinion about default aliases, I only had a narrow point,
> ie, on the list of impactful things that helps Git newcomers around my
> circles, aliases would not score very high. Those who love the command
> line among the more enthusiastic learners will set those aliases themselves
> anyway.

Sure, initially aliases would not help them very much, but after the
initial learning period when they actually start using git for real,
then aliases help tremendously.

Cheers.

-- 
Felipe Contreras

Re: The git spring cleanup challenge completion

[Theodore Ts'o]

On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:
> Atharva Raykar wrote:
> > I can imagine aliases like 'co' only adding to the overload of
> > information if an instructor is not careful. FWIW, I have never seen a new
> > user complain about the length of the typing, it's usually with the plethora
> > of unintelligible (to them) options that each command has when they open the
> > Git man pages, which adds more fear.
> 
> This is one of the reasons I suggested to split git into two binaries:
> git for normal users, and git-tool for all the plumbing not many humans
> use.

It might be that the answer for the problem Atharva has described
would be for someone so include to create a new front-end to git ---
call it "sg", for simplified git", or "gt" for git tool (different
from the "git-tool suggested by Felipe), etc.

It could be an extremely opinionated subset of git's functionality;
for example, it could be one where the index is completely hidden from
the user, so you never need to type "sg add" when modifying a file,
but only when adding a new file to be under source code management
(e.g., that "sg commit" would effectively imply "git add -u ; git
commit"), and so on.  Since the index doesn't conceptually exist in
the sg interface, then "sg reset" would only have the meaning of "git
reset --hard", etc.

By definition this simplified front-end to git would have a subset of
the functionality of "full git", but that's OK.  The whole goal would
be to make something super newbie-friendly --- the equivalent of a
"Mac OS-like" interface, that perhaps doesn't have the power of
someone who opens up a shell and uses tools like awk or perl, but is
good enough "for the rest of the human race".

Note that this doesn't have to be an official "git" ccommunity
initiative; anyone could try to create such one of these things (and I
believe a few things exist already).

Making it a non-goal that this "user friendly" front end doesn't have
to have the full functionality of git, and its main goal is to allow
the use of different user interface design choices made by git, might
be much simpler than trying to change git, which would require having
the argument over which functionality is used by "normal users", and
which features should be exiled to "git-pull" as being "fringe"
features.

						- Ted

Re: The git spring cleanup challenge completion

[Felipe Contreras]

Theodore Ts'o wrote:
> On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:
> > Atharva Raykar wrote:
> > > I can imagine aliases like 'co' only adding to the overload of
> > > information if an instructor is not careful. FWIW, I have never seen a new
> > > user complain about the length of the typing, it's usually with the plethora
> > > of unintelligible (to them) options that each command has when they open the
> > > Git man pages, which adds more fear.
> > 
> > This is one of the reasons I suggested to split git into two binaries:
> > git for normal users, and git-tool for all the plumbing not many humans
> > use.
> 
> It might be that the answer for the problem Atharva has described
> would be for someone so include to create a new front-end to git ---
> call it "sg", for simplified git", or "gt" for git tool (different
> from the "git-tool suggested by Felipe), etc.
> 
> It could be an extremely opinionated subset of git's functionality;
> for example, it could be one where the index is completely hidden from
> the user, so you never need to type "sg add" when modifying a file,
> but only when adding a new file to be under source code management
> (e.g., that "sg commit" would effectively imply "git add -u ; git
> commit"), and so on.  Since the index doesn't conceptually exist in
> the sg interface, then "sg reset" would only have the meaning of "git
> reset --hard", etc.
> 
> By definition this simplified front-end to git would have a subset of
> the functionality of "full git", but that's OK.  The whole goal would
> be to make something super newbie-friendly --- the equivalent of a
> "Mac OS-like" interface, that perhaps doesn't have the power of
> someone who opens up a shell and uses tools like awk or perl, but is
> good enough "for the rest of the human race".
> 
> Note that this doesn't have to be an official "git" ccommunity
> initiative; anyone could try to create such one of these things (and I
> believe a few things exist already).
> 
> Making it a non-goal that this "user friendly" front end doesn't have
> to have the full functionality of git, and its main goal is to allow
> the use of different user interface design choices made by git, might
> be much simpler than trying to change git, which would require having
> the argument over which functionality is used by "normal users", and
> which features should be exiled to "git-pull" as being "fringe"
> features.

I think there's some value in that idea but that doesn't solve the same
problem my suggestion solves. Basically there's too many commands in
`man git`. Splitting the git binary would allow us to only put the
important commands in `man git`.

I think having too many commands overwhelms many newcomers, because they
don't know which it's important for them to learn and which are
basically noise.

-- 
Felipe Contreras

Re: The git spring cleanup challenge completion

[Ævar Arnfjörð Bjarmason]

On Sun, Jul 04 2021, Felipe Contreras wrote:

> Theodore Ts'o wrote:
>> On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:
>> > Atharva Raykar wrote:
>> > > I can imagine aliases like 'co' only adding to the overload of
>> > > information if an instructor is not careful. FWIW, I have never seen a new
>> > > user complain about the length of the typing, it's usually with the plethora
>> > > of unintelligible (to them) options that each command has when they open the
>> > > Git man pages, which adds more fear.
>> > 
>> > This is one of the reasons I suggested to split git into two binaries:
>> > git for normal users, and git-tool for all the plumbing not many humans
>> > use.
>> 
>> It might be that the answer for the problem Atharva has described
>> would be for someone so include to create a new front-end to git ---
>> call it "sg", for simplified git", or "gt" for git tool (different
>> from the "git-tool suggested by Felipe), etc.
>> 
>> It could be an extremely opinionated subset of git's functionality;
>> for example, it could be one where the index is completely hidden from
>> the user, so you never need to type "sg add" when modifying a file,
>> but only when adding a new file to be under source code management
>> (e.g., that "sg commit" would effectively imply "git add -u ; git
>> commit"), and so on.  Since the index doesn't conceptually exist in
>> the sg interface, then "sg reset" would only have the meaning of "git
>> reset --hard", etc.
>> 
>> By definition this simplified front-end to git would have a subset of
>> the functionality of "full git", but that's OK.  The whole goal would
>> be to make something super newbie-friendly --- the equivalent of a
>> "Mac OS-like" interface, that perhaps doesn't have the power of
>> someone who opens up a shell and uses tools like awk or perl, but is
>> good enough "for the rest of the human race".
>> 
>> Note that this doesn't have to be an official "git" ccommunity
>> initiative; anyone could try to create such one of these things (and I
>> believe a few things exist already).
>> 
>> Making it a non-goal that this "user friendly" front end doesn't have
>> to have the full functionality of git, and its main goal is to allow
>> the use of different user interface design choices made by git, might
>> be much simpler than trying to change git, which would require having
>> the argument over which functionality is used by "normal users", and
>> which features should be exiled to "git-pull" as being "fringe"
>> features.
>
> I think there's some value in that idea but that doesn't solve the same
> problem my suggestion solves. Basically there's too many commands in
> `man git`. Splitting the git binary would allow us to only put the
> important commands in `man git`.
>
> I think having too many commands overwhelms many newcomers, because they
> don't know which it's important for them to learn and which are
> basically noise.

I'm very much for the idea of a cleanup of "man git", but I don't think
we need to introduce a git-tool(1) for that.

E.g. "man perl" is a good example of where we should be
headed. I.e. right off the bat in "man git" we have a long listing of
command-line options to git itself, things like --exec-path and
--no-optional-locks etc. are useful to almost no casual user.

We should really split everything except a passing mention of -p, -P, -c
etc. into a "man gitrun" or something (just like perl has "man
perlrun"), ditto the whole "ENVIRONMENT VARIABLES" section.

Our whole list of "porcelain" v.s. "plumbing" also needs to be
refactored. I've been meaning to get to that[1], i.e. the
plumbing/porcelain split we present in "man git" isn't the ground truth
at all. We need some manual page that covers commands, but also exit
codes, and specific options (e.g. "git-status" is either porcelain or
plumbing depending on the mode it's in, same for "log" etc.).

If I try to print https://git-scm.com/docs/git in my browser it's 36
pages, it's only on page 34 that we start to discuss[2] tutorials
etc. in a bit more detail than in the starting DESCRIPTION section. By
comparison e.g. perl (probably a more complex tool overall) is 2-3 pages
of just pointing you at other documentation appropriate to various
sub-topics.

1. https://lore.kernel.org/git/878sa7xujm.fsf@evledraar.gmail.com/
2. https://git-scm.com/docs/git#_discussion

Re: The git spring cleanup challenge completion

[Felipe Contreras]

Ævar Arnfjörð Bjarmason wrote:
> On Sun, Jul 04 2021, Felipe Contreras wrote:

> > I think there's some value in that idea but that doesn't solve the same
> > problem my suggestion solves. Basically there's too many commands in
> > `man git`. Splitting the git binary would allow us to only put the
> > important commands in `man git`.
> >
> > I think having too many commands overwhelms many newcomers, because they
> > don't know which it's important for them to learn and which are
> > basically noise.
> 
> I'm very much for the idea of a cleanup of "man git", but I don't think
> we need to introduce a git-tool(1) for that.

Indeed, it's not *necessary*, but it would help tremendously.

> E.g. "man perl" is a good example of where we should be
> headed. I.e. right off the bat in "man git" we have a long listing of
> command-line options to git itself, things like --exec-path and
> --no-optional-locks etc. are useful to almost no casual user.
> 
> We should really split everything except a passing mention of -p, -P, -c
> etc. into a "man gitrun" or something (just like perl has "man
> perlrun"), ditto the whole "ENVIRONMENT VARIABLES" section.

I like that. For the record zsh also splits man pages that way.

I would prefer `git-run` (or `git-core`) though, althought if somebody
at some point wants to create such a built-in that would be problematic.

-- 
Felipe Contreras