* The git spring cleanup challenge completion @ 2021-07-02 22:49 Felipe Contreras 2021-07-03 5:53 ` Bagas Sanjaya 2021-07-03 14:00 ` Atharva Raykar 0 siblings, 2 replies; 9+ messages in thread From: Felipe Contreras @ 2021-07-02 22:49 UTC (permalink / raw) To: git 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-02 22:49 The git spring cleanup challenge completion Felipe Contreras @ 2021-07-03 5:53 ` Bagas Sanjaya 2021-07-03 17:33 ` Felipe Contreras 2021-07-03 14:00 ` Atharva Raykar 1 sibling, 1 reply; 9+ messages in thread From: Bagas Sanjaya @ 2021-07-03 5:53 UTC (permalink / raw) To: Felipe Contreras, git 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-03 5:53 ` Bagas Sanjaya @ 2021-07-03 17:33 ` Felipe Contreras 0 siblings, 0 replies; 9+ messages in thread From: Felipe Contreras @ 2021-07-03 17:33 UTC (permalink / raw) To: Bagas Sanjaya, Felipe Contreras, git 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-02 22:49 The git spring cleanup challenge completion Felipe Contreras 2021-07-03 5:53 ` Bagas Sanjaya @ 2021-07-03 14:00 ` Atharva Raykar 2021-07-03 18:16 ` Felipe Contreras 1 sibling, 1 reply; 9+ messages in thread From: Atharva Raykar @ 2021-07-03 14:00 UTC (permalink / raw) To: Felipe Contreras; +Cc: Git List 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 ಅಥರ್ವ ರಾಯ್ಕರ್ अथर्व रायकर ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-03 14:00 ` Atharva Raykar @ 2021-07-03 18:16 ` Felipe Contreras 2021-07-04 0:45 ` Theodore Ts'o 0 siblings, 1 reply; 9+ messages in thread From: Felipe Contreras @ 2021-07-03 18:16 UTC (permalink / raw) To: Atharva Raykar, Felipe Contreras; +Cc: Git List 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-03 18:16 ` Felipe Contreras @ 2021-07-04 0:45 ` Theodore Ts'o 2021-07-04 17:23 ` Felipe Contreras 0 siblings, 1 reply; 9+ messages in thread From: Theodore Ts'o @ 2021-07-04 0:45 UTC (permalink / raw) To: Felipe Contreras; +Cc: Atharva Raykar, Git List 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-04 0:45 ` Theodore Ts'o @ 2021-07-04 17:23 ` Felipe Contreras 2021-07-04 20:47 ` Ævar Arnfjörð Bjarmason 0 siblings, 1 reply; 9+ messages in thread From: Felipe Contreras @ 2021-07-04 17:23 UTC (permalink / raw) To: Theodore Ts'o, Felipe Contreras; +Cc: Atharva Raykar, Git List 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-04 17:23 ` Felipe Contreras @ 2021-07-04 20:47 ` Ævar Arnfjörð Bjarmason 2021-07-06 22:31 ` Felipe Contreras 0 siblings, 1 reply; 9+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2021-07-04 20:47 UTC (permalink / raw) To: Felipe Contreras; +Cc: Theodore Ts'o, Atharva Raykar, Git List 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: The git spring cleanup challenge completion 2021-07-04 20:47 ` Ævar Arnfjörð Bjarmason @ 2021-07-06 22:31 ` Felipe Contreras 0 siblings, 0 replies; 9+ messages in thread From: Felipe Contreras @ 2021-07-06 22:31 UTC (permalink / raw) To: Ævar Arnfjörð Bjarmason, Felipe Contreras Cc: Theodore Ts'o, Atharva Raykar, Git List Æ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 ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2021-07-06 22:31 UTC | newest] Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-07-02 22:49 The git spring cleanup challenge completion Felipe Contreras 2021-07-03 5:53 ` Bagas Sanjaya 2021-07-03 17:33 ` Felipe Contreras 2021-07-03 14:00 ` Atharva Raykar 2021-07-03 18:16 ` Felipe Contreras 2021-07-04 0:45 ` Theodore Ts'o 2021-07-04 17:23 ` Felipe Contreras 2021-07-04 20:47 ` Ævar Arnfjörð Bjarmason 2021-07-06 22:31 ` Felipe Contreras
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).