Re: The git spring cleanup challenge completion

On Sun, Jul 04 2021, Felipe Contreras wrote:

Theodore Ts'o wrote:

quoted

On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:

quoted

Atharva Raykar wrote:

quoted

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/ (local)
2. https://git-scm.com/docs/git#_discussion