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@xxxxxxxxxxxxxxxxxxx/ 2. https://git-scm.com/docs/git#_discussion
