{"thread":{"id":"56043","subject":"The git spring cleanup challenge completion","startedAt":"2021-07-02T22:49:21Z","lastAt":"2021-07-06T22:31:31Z","messageCount":9,"participants":["Felipe Contreras","Bagas Sanjaya","Atharva Raykar","Theodore Ts'o","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"429089","messageId":"60df97ed24687_34a92088a@natae.notmuch","threadId":"56043","inReplyTo":null,"subject":"The git spring cleanup challenge completion","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-02T22:49:17Z","receivedAt":"2021-07-02T22:49:21Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Hello,\n\nOne month ago I suggested the git spring cleanup challenge [1], which\nafter 50 replies can probably be considered a success.\n\nAfter one month of trying my best not to add many configurations, this\nis my final .gitconfig:\n\n  [merge]\n    conflictstyle = diff3\n  [alias]\n    co = commit -v -s\n    br = branch\n\nJudging from the discussion, diff3 should definitely become the new\ndefault conflict style. I already sent some patches [2] to try to start\nmoving in that direction, but unfortunately it doesn't seem to be that\neasy because many commands simply ignore that configuration, while\nothers have issues with the configuration and the command line. Many\nprobably need a new command line argument to specify the desired\nconflict style. A lot of work is needed.\n\nNot to mention the two new proposals to have a new, better diff3: zdiff3\n[3] [4]. These come from a proposal from Uwe Kleine-König in 2013 [5].\n\n\nOther than that, it's fair to say that *everyone* needs some command\naliases to use git. This past month shell completions have saved me, but\nnot completely. I can't imagine how a newcomer must feel using git\nwithout any alias.\n\nI sent some patches to attempt to have some standard default aliases\n[6], also, there's this old thread where default aliases were discussed\nat depth [7].\n\nAnother uncontroversial configuration everyone agrees should be the\ndefault is `rerere.enabled`. Although `rerere.autoupdate` is more\ncontroversial, I don't see why it cannot be considered too.\n\nHere's a few other interesting configurations:\n\n  * rebase.autosquash = true\n  * rebase.autostash = true \n  * commit.verbose = true\n  * diff.colorMoved = true\n  * grep.patternType = perl\n  * alias.undo = reset --hard @{1}\n  * feature.experimental = true\n  * branch.sort = committerdate\n  * diff.algorithm = histogram\n\nI for one can't wait to finally have proper aliases again.\n\nThat was painful.\n\nCheers.\n\n[1] https://lore.kernel.org/git/60b5d281552d6_e359f20828@natae.notmuch/\n[2] https://lore.kernel.org/git/20210622002714.1720891-1-felipe.contreras@gmail.com/\n[3] https://lore.kernel.org/git/20210613143155.836591-1-felipe.contreras@gmail.com/\n[4] https://lore.kernel.org/git/b7561a67c192d4bdede47fee5b7b1cb30c44b785.1623734171.git.gitgitgadget@gmail.com/\n[5] https://lore.kernel.org/git/1362602202-29749-1-git-send-email-u.kleine-koenig@pengutronix.de/\n[6] https://lore.kernel.org/git/20210702100506.1422429-1-felipe.contreras@gmail.com/T/#t\n[7] https://lore.kernel.org/git/CAMP44s17h4Tjg+VaMF0atLep8t-0HVp4UDr1WE2wYnEuZ07eaQ@mail.gmail.com/\n\n-- \nFelipe Contreras"},{"id":"429101","messageId":"cd495a08-bbf7-35f8-e1a8-a87cdc9c3ef1@gmail.com","threadId":"56043","inReplyTo":"60df97ed24687_34a92088a@natae.notmuch","subject":"Re: The git spring cleanup challenge completion","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-07-03T05:53:57Z","receivedAt":"2021-07-03T05:54:23Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 03/07/21 05.49, Felipe Contreras wrote:\n> Other than that, it's fair to say that *everyone* needs some command\n> aliases to use git. This past month shell completions have saved me, but\n> not completely. I can't imagine how a newcomer must feel using git\n> without any alias.\n\nI personally use git *sans* aliases. I prefer writing full commands \n(like `git checkout`) rather than shorter aliases (like `git co`) so \nthat I know what my intentions are.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"429125","messageId":"C19D6C61-D62A-4344-BA1C-A532EB4FEFFE@gmail.com","threadId":"56043","inReplyTo":"60df97ed24687_34a92088a@natae.notmuch","subject":"Re: The git spring cleanup challenge completion","fromName":"Atharva Raykar","fromEmail":"raykar.ath@gmail.com","sentAt":"2021-07-03T14:00:22Z","receivedAt":"2021-07-03T14:00:35Z","isPatch":false,"sender":{"key":"raykar.ath@gmail.com","avatar":"https://avatars.githubusercontent.com/u/24277692?v=4"},"body":"On 03-Jul-2021, at 04:19, Felipe Contreras <felipe.contreras@gmail.com> wrote:\n> \n> [...]\n> Other than that, it's fair to say that *everyone* needs some command\n> aliases to use git. This past month shell completions have saved me, but\n> not completely. I can't imagine how a newcomer must feel using git\n> without any alias.\n\nTLDR: I don't think young, first-time learners of Git would mind the lack\nof aliases. I cannot speak for people coming from other VCS's.\n\n------ Long Version -------\n\nHi, maybe I can help bring some perspective on how newcomers view and use\nGit. I help run an Open Source club in my University, and one of the first\nthings we help a lot of new contributors with is teaching Git.\n\nI have conducted multiple workshops over the last two years, so I have\nsome idea of what the usual struggles and pain points are. I also have\nsome recollection of what it's like being a new user.\n\nMost of these new users have never used any kind of VCS before, so half\nthe problem is the overload of all these new concepts of branches,\nchecking out, staging area, committing, pushing, pulling, etc.\n\nUsers are not able to properly map the name of these commands with what\nit actually does. Most of the issues stem from trying to memorise these\ncommands as a series of mantras and applying them without knowing what\nis actually happening.\n\nUsers are confused about why there is an \"add\", and then a \"commit\".\nIt seems conceptually similar to them. The difference between reset,\nrestore, revert (and even rebase) is also a pain point, because those\nwords sound very similar.\n\nCombine the lack of understanding of what Git is actually doing, with the\nfear of losing work, and you get the perfect storm of a difficult\nexperience.\n\nFor most new users Git is unusable, unless you explain to them the right\nmental model of Git being a graph of immutable commit objects with\npointers to access their contents. In my opinion, trying to make this\nmodel more transparent to a new user is the best way to improve their\nexperience.\n\nWhat new users do not have a problem with is a lack of aliases, because\nthey carry no previous expectation from other VCS's, as Git is always their\nfirst one. I can imagine aliases like 'co' only adding to the overload of\ninformation if an instructor is not careful. FWIW, I have never seen a new\nuser complain about the length of the typing, it's usually with the plethora\nof unintelligible (to them) options that each command has when they open the\nGit man pages, which adds more fear.\n\nI do not have an opinion about default aliases, I only had a narrow point,\nie, on the list of impactful things that helps Git newcomers around my\ncircles, aliases would not score very high. Those who love the command\nline among the more enthusiastic learners will set those aliases themselves\nanyway.\n\n---\nAtharva Raykar\nಅಥರ್ವ ರಾಯ್ಕರ್\nअथर्व रायकर\n\n"},{"id":"429129","messageId":"60e09f5e70ae5_92c020866@natae.notmuch","threadId":"56043","inReplyTo":"cd495a08-bbf7-35f8-e1a8-a87cdc9c3ef1@gmail.com","subject":"Re: The git spring cleanup challenge completion","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-03T17:33:18Z","receivedAt":"2021-07-03T17:33:23Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 03/07/21 05.49, Felipe Contreras wrote:\n> > Other than that, it's fair to say that *everyone* needs some command\n> > aliases to use git. This past month shell completions have saved me, but\n> > not completely. I can't imagine how a newcomer must feel using git\n> > without any alias.\n> \n> I personally use git *sans* aliases. I prefer writing full commands \n> (like `git checkout`) rather than shorter aliases (like `git co`) so \n> that I know what my intentions are.\n\nOK. Virtually everyone.\n\nHave you tried aliases? I just went through a month of getting outside\nmy confort zone.\n\n-- \nFelipe Contreras\n"},{"id":"429131","messageId":"60e0a9707e09a_2f7208f2@natae.notmuch","threadId":"56043","inReplyTo":"C19D6C61-D62A-4344-BA1C-A532EB4FEFFE@gmail.com","subject":"Re: The git spring cleanup challenge completion","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-03T18:16:16Z","receivedAt":"2021-07-03T18:16:24Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Atharva Raykar wrote:\n> On 03-Jul-2021, at 04:19, Felipe Contreras <felipe.contreras@gmail.com> wrote:\n> > \n> > [...]\n> > Other than that, it's fair to say that *everyone* needs some command\n> > aliases to use git. This past month shell completions have saved me, but\n> > not completely. I can't imagine how a newcomer must feel using git\n> > without any alias.\n> \n> TLDR: I don't think young, first-time learners of Git would mind the lack\n> of aliases. I cannot speak for people coming from other VCS's.\n\nThat's not the same thing. Of course a user wouldn't mind the lack of\ncertain feature if he doesn't know he is missing that feature in the\nfirst place.\n\nHumans went for thousands of years using luggage without wheels, does\nthat mean they \"didn't mind\" luggage without wheels? They had nothing to\ncompare it to, so they of course didn't complain, but that doesn't mean\nthey were \"fine\".\n\nIn order for them to know if they mind it or not they would first need\nto try them.\n\n> ------ Long Version -------\n> \n> Hi, maybe I can help bring some perspective on how newcomers view and use\n> Git. I help run an Open Source club in my University, and one of the first\n> things we help a lot of new contributors with is teaching Git.\n> \n> I have conducted multiple workshops over the last two years, so I have\n> some idea of what the usual struggles and pain points are. I also have\n> some recollection of what it's like being a new user.\n> \n> Most of these new users have never used any kind of VCS before, so half\n> the problem is the overload of all these new concepts of branches,\n> checking out, staging area, committing, pushing, pulling, etc.\n\nSure, that's understandable.\n\n> Users are not able to properly map the name of these commands with what\n> it actually does. Most of the issues stem from trying to memorise these\n> commands as a series of mantras and applying them without knowing what\n> is actually happening.\n\nI recall using git that way a long time ago.\n\n> Users are confused about why there is an \"add\", and then a \"commit\".\n> It seems conceptually similar to them. The difference between reset,\n> restore, revert (and even rebase) is also a pain point, because those\n> words sound very similar.\n\nYeap, I remember that.\n\n> Combine the lack of understanding of what Git is actually doing, with the\n> fear of losing work, and you get the perfect storm of a difficult\n> experience.\n> \n> For most new users Git is unusable, unless you explain to them the right\n> mental model of Git being a graph of immutable commit objects with\n> pointers to access their contents. In my opinion, trying to make this\n> model more transparent to a new user is the best way to improve their\n> experience.\n\nSure, I see those pain points, and I have sent plenty of patches to\nimprove that experience, but none of them have been applied.\n\n> What new users do not have a problem with is a lack of aliases, because\n> they carry no previous expectation from other VCS's, as Git is always their\n> first one.\n\nSure, when they are learning git they don't need aliases, but after they\nbecome fluent and can do some basic workflow without looking to cheat\nsheets they *immediately* would benefit from them.\n\n> I can imagine aliases like 'co' only adding to the overload of\n> information if an instructor is not careful. FWIW, I have never seen a new\n> user complain about the length of the typing, it's usually with the plethora\n> of unintelligible (to them) options that each command has when they open the\n> Git man pages, which adds more fear.\n\nThis is one of the reasons I suggested to split git into two binaries:\ngit for normal users, and git-tool for all the plumbing not many humans\nuse.\n\n> I do not have an opinion about default aliases, I only had a narrow point,\n> ie, on the list of impactful things that helps Git newcomers around my\n> circles, aliases would not score very high. Those who love the command\n> line among the more enthusiastic learners will set those aliases themselves\n> anyway.\n\nSure, initially aliases would not help them very much, but after the\ninitial learning period when they actually start using git for real,\nthen aliases help tremendously.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429143","messageId":"YOEEjwbMPRmWOmrM@mit.edu","threadId":"56043","inReplyTo":"60e0a9707e09a_2f7208f2@natae.notmuch","subject":"Re: The git spring cleanup challenge completion","fromName":"Theodore Ts'o","fromEmail":"tytso@mit.edu","sentAt":"2021-07-04T00:45:03Z","receivedAt":"2021-07-04T00:45:09Z","isPatch":false,"sender":{"key":"tytso@mit.edu","avatar":"https://avatars.githubusercontent.com/u/51416?v=4"},"body":"On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:\n> Atharva Raykar wrote:\n> > I can imagine aliases like 'co' only adding to the overload of\n> > information if an instructor is not careful. FWIW, I have never seen a new\n> > user complain about the length of the typing, it's usually with the plethora\n> > of unintelligible (to them) options that each command has when they open the\n> > Git man pages, which adds more fear.\n> \n> This is one of the reasons I suggested to split git into two binaries:\n> git for normal users, and git-tool for all the plumbing not many humans\n> use.\n\nIt might be that the answer for the problem Atharva has described\nwould be for someone so include to create a new front-end to git ---\ncall it \"sg\", for simplified git\", or \"gt\" for git tool (different\nfrom the \"git-tool suggested by Felipe), etc.\n\nIt could be an extremely opinionated subset of git's functionality;\nfor example, it could be one where the index is completely hidden from\nthe user, so you never need to type \"sg add\" when modifying a file,\nbut only when adding a new file to be under source code management\n(e.g., that \"sg commit\" would effectively imply \"git add -u ; git\ncommit\"), and so on.  Since the index doesn't conceptually exist in\nthe sg interface, then \"sg reset\" would only have the meaning of \"git\nreset --hard\", etc.\n\nBy definition this simplified front-end to git would have a subset of\nthe functionality of \"full git\", but that's OK.  The whole goal would\nbe to make something super newbie-friendly --- the equivalent of a\n\"Mac OS-like\" interface, that perhaps doesn't have the power of\nsomeone who opens up a shell and uses tools like awk or perl, but is\ngood enough \"for the rest of the human race\".\n\nNote that this doesn't have to be an official \"git\" ccommunity\ninitiative; anyone could try to create such one of these things (and I\nbelieve a few things exist already).\n\nMaking it a non-goal that this \"user friendly\" front end doesn't have\nto have the full functionality of git, and its main goal is to allow\nthe use of different user interface design choices made by git, might\nbe much simpler than trying to change git, which would require having\nthe argument over which functionality is used by \"normal users\", and\nwhich features should be exiled to \"git-pull\" as being \"fringe\"\nfeatures.\n\n\t\t\t\t\t\t- Ted\n"},{"id":"429167","messageId":"60e1ee7a3cfbc_6d11d20811@natae.notmuch","threadId":"56043","inReplyTo":"YOEEjwbMPRmWOmrM@mit.edu","subject":"Re: The git spring cleanup challenge completion","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-04T17:23:06Z","receivedAt":"2021-07-04T17:23:22Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Theodore Ts'o wrote:\n> On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:\n> > Atharva Raykar wrote:\n> > > I can imagine aliases like 'co' only adding to the overload of\n> > > information if an instructor is not careful. FWIW, I have never seen a new\n> > > user complain about the length of the typing, it's usually with the plethora\n> > > of unintelligible (to them) options that each command has when they open the\n> > > Git man pages, which adds more fear.\n> > \n> > This is one of the reasons I suggested to split git into two binaries:\n> > git for normal users, and git-tool for all the plumbing not many humans\n> > use.\n> \n> It might be that the answer for the problem Atharva has described\n> would be for someone so include to create a new front-end to git ---\n> call it \"sg\", for simplified git\", or \"gt\" for git tool (different\n> from the \"git-tool suggested by Felipe), etc.\n> \n> It could be an extremely opinionated subset of git's functionality;\n> for example, it could be one where the index is completely hidden from\n> the user, so you never need to type \"sg add\" when modifying a file,\n> but only when adding a new file to be under source code management\n> (e.g., that \"sg commit\" would effectively imply \"git add -u ; git\n> commit\"), and so on.  Since the index doesn't conceptually exist in\n> the sg interface, then \"sg reset\" would only have the meaning of \"git\n> reset --hard\", etc.\n> \n> By definition this simplified front-end to git would have a subset of\n> the functionality of \"full git\", but that's OK.  The whole goal would\n> be to make something super newbie-friendly --- the equivalent of a\n> \"Mac OS-like\" interface, that perhaps doesn't have the power of\n> someone who opens up a shell and uses tools like awk or perl, but is\n> good enough \"for the rest of the human race\".\n> \n> Note that this doesn't have to be an official \"git\" ccommunity\n> initiative; anyone could try to create such one of these things (and I\n> believe a few things exist already).\n> \n> Making it a non-goal that this \"user friendly\" front end doesn't have\n> to have the full functionality of git, and its main goal is to allow\n> the use of different user interface design choices made by git, might\n> be much simpler than trying to change git, which would require having\n> the argument over which functionality is used by \"normal users\", and\n> which features should be exiled to \"git-pull\" as being \"fringe\"\n> features.\n\nI think there's some value in that idea but that doesn't solve the same\nproblem my suggestion solves. Basically there's too many commands in\n`man git`. Splitting the git binary would allow us to only put the\nimportant commands in `man git`.\n\nI think having too many commands overwhelms many newcomers, because they\ndon't know which it's important for them to learn and which are\nbasically noise.\n\n-- \nFelipe Contreras\n"},{"id":"429168","messageId":"87wnq57q9n.fsf@evledraar.gmail.com","threadId":"56043","inReplyTo":"60e1ee7a3cfbc_6d11d20811@natae.notmuch","subject":"Re: The git spring cleanup challenge completion","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-04T20:47:32Z","receivedAt":"2021-07-04T20:55:38Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sun, Jul 04 2021, Felipe Contreras wrote:\n\n> Theodore Ts'o wrote:\n>> On Sat, Jul 03, 2021 at 01:16:16PM -0500, Felipe Contreras wrote:\n>> > Atharva Raykar wrote:\n>> > > I can imagine aliases like 'co' only adding to the overload of\n>> > > information if an instructor is not careful. FWIW, I have never seen a new\n>> > > user complain about the length of the typing, it's usually with the plethora\n>> > > of unintelligible (to them) options that each command has when they open the\n>> > > Git man pages, which adds more fear.\n>> > \n>> > This is one of the reasons I suggested to split git into two binaries:\n>> > git for normal users, and git-tool for all the plumbing not many humans\n>> > use.\n>> \n>> It might be that the answer for the problem Atharva has described\n>> would be for someone so include to create a new front-end to git ---\n>> call it \"sg\", for simplified git\", or \"gt\" for git tool (different\n>> from the \"git-tool suggested by Felipe), etc.\n>> \n>> It could be an extremely opinionated subset of git's functionality;\n>> for example, it could be one where the index is completely hidden from\n>> the user, so you never need to type \"sg add\" when modifying a file,\n>> but only when adding a new file to be under source code management\n>> (e.g., that \"sg commit\" would effectively imply \"git add -u ; git\n>> commit\"), and so on.  Since the index doesn't conceptually exist in\n>> the sg interface, then \"sg reset\" would only have the meaning of \"git\n>> reset --hard\", etc.\n>> \n>> By definition this simplified front-end to git would have a subset of\n>> the functionality of \"full git\", but that's OK.  The whole goal would\n>> be to make something super newbie-friendly --- the equivalent of a\n>> \"Mac OS-like\" interface, that perhaps doesn't have the power of\n>> someone who opens up a shell and uses tools like awk or perl, but is\n>> good enough \"for the rest of the human race\".\n>> \n>> Note that this doesn't have to be an official \"git\" ccommunity\n>> initiative; anyone could try to create such one of these things (and I\n>> believe a few things exist already).\n>> \n>> Making it a non-goal that this \"user friendly\" front end doesn't have\n>> to have the full functionality of git, and its main goal is to allow\n>> the use of different user interface design choices made by git, might\n>> be much simpler than trying to change git, which would require having\n>> the argument over which functionality is used by \"normal users\", and\n>> which features should be exiled to \"git-pull\" as being \"fringe\"\n>> features.\n>\n> I think there's some value in that idea but that doesn't solve the same\n> problem my suggestion solves. Basically there's too many commands in\n> `man git`. Splitting the git binary would allow us to only put the\n> important commands in `man git`.\n>\n> I think having too many commands overwhelms many newcomers, because they\n> don't know which it's important for them to learn and which are\n> basically noise.\n\nI'm very much for the idea of a cleanup of \"man git\", but I don't think\nwe need to introduce a git-tool(1) for that.\n\nE.g. \"man perl\" is a good example of where we should be\nheaded. I.e. right off the bat in \"man git\" we have a long listing of\ncommand-line options to git itself, things like --exec-path and\n--no-optional-locks etc. are useful to almost no casual user.\n\nWe should really split everything except a passing mention of -p, -P, -c\netc. into a \"man gitrun\" or something (just like perl has \"man\nperlrun\"), ditto the whole \"ENVIRONMENT VARIABLES\" section.\n\nOur whole list of \"porcelain\" v.s. \"plumbing\" also needs to be\nrefactored. I've been meaning to get to that[1], i.e. the\nplumbing/porcelain split we present in \"man git\" isn't the ground truth\nat all. We need some manual page that covers commands, but also exit\ncodes, and specific options (e.g. \"git-status\" is either porcelain or\nplumbing depending on the mode it's in, same for \"log\" etc.).\n\nIf I try to print https://git-scm.com/docs/git in my browser it's 36\npages, it's only on page 34 that we start to discuss[2] tutorials\netc. in a bit more detail than in the starting DESCRIPTION section. By\ncomparison e.g. perl (probably a more complex tool overall) is 2-3 pages\nof just pointing you at other documentation appropriate to various\nsub-topics.\n\n1. https://lore.kernel.org/git/878sa7xujm.fsf@evledraar.gmail.com/\n2. https://git-scm.com/docs/git#_discussion\n"},{"id":"429374","messageId":"60e4d9c07914e_1c42812081a@natae.notmuch","threadId":"56043","inReplyTo":"87wnq57q9n.fsf@evledraar.gmail.com","subject":"Re: The git spring cleanup challenge completion","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-06T22:31:28Z","receivedAt":"2021-07-06T22:31:31Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> On Sun, Jul 04 2021, Felipe Contreras wrote:\n\n> > I think there's some value in that idea but that doesn't solve the same\n> > problem my suggestion solves. Basically there's too many commands in\n> > `man git`. Splitting the git binary would allow us to only put the\n> > important commands in `man git`.\n> >\n> > I think having too many commands overwhelms many newcomers, because they\n> > don't know which it's important for them to learn and which are\n> > basically noise.\n> \n> I'm very much for the idea of a cleanup of \"man git\", but I don't think\n> we need to introduce a git-tool(1) for that.\n\nIndeed, it's not *necessary*, but it would help tremendously.\n\n> E.g. \"man perl\" is a good example of where we should be\n> headed. I.e. right off the bat in \"man git\" we have a long listing of\n> command-line options to git itself, things like --exec-path and\n> --no-optional-locks etc. are useful to almost no casual user.\n> \n> We should really split everything except a passing mention of -p, -P, -c\n> etc. into a \"man gitrun\" or something (just like perl has \"man\n> perlrun\"), ditto the whole \"ENVIRONMENT VARIABLES\" section.\n\nI like that. For the record zsh also splits man pages that way.\n\nI would prefer `git-run` (or `git-core`) though, althought if somebody\nat some point wants to create such a built-in that would be problematic.\n\n-- \nFelipe Contreras"}]}