Weekly Edition
Return to the Front page
| |||||||||||||
Feature removal sparks Git flamewarRemoving features from a tool is never easy. Once there is enough of a user base to complain about annoyances, there is also a vocal group that uses and likes those same annoyances. The recent removal of the git-foo style commands from Git is just such a case, but many of those using those commands did not find out about the removal until after the change was made, which only served to increase their outrage. Until version 1.6.0, Git has always had two ways to invoke the same functionality: git foo and git-foo. This was done by installing many—usually more than 100—different entries into /usr/bin for all of the different git subcommands. Some were concerned that Git was polluting that directory, but the bigger issue was the effect on new users. Partially because of shell autocompletion, a new user might be overwhelmed by the number of different Git commands available; even regular users might find it difficult to find the command they are looking for if they have to sort through 100 or more. Many of the Git subcommands that exist are not necessarily regularly used. There are quite a number of "plumbing" commands that rarely, if ever, should be invoked by users. Those are best hidden from view, which can be done by moving them out of /usr/bin. This has been done for the 1.6.0 release, but Junio Hamano opened up a can of worms when he posted a request for discussion about taking the next step to the Git mailing list. In the 1.6.0 release, the only things exposed in /usr/bin are the git binary itself along with a few other utilities; the rest have been moved to /usr/libexec/git-core. The hard links for each of the git-foo commands have been maintained in the new location, which allows folks that still want the old behavior to get it by adding:
PATH="$PATH:$(git --exec-path)"
to .bashrc (or some other startup file, depending on the shell).
This would allow users—especially scripts—to continue using the
dash versions of commands.
Unfortunately, for many users, the first they heard about this change was when things stopped working after they installed 1.6.0. The Git team admittedly did not get the word out very well; by trying to be nice, they missed an opportunity to make users notice the change. As Hamano puts it:
But that niceness backfired. Many people seem to argue now that we should
have annoyed people by throwing loud deprecation notices to stderr when
they typed "git-foo", and we should have risked breaking their scripts iff
they relied on not seeing anything extra on the stderr.
Hamano got caught in the middle to some extent as he wasn't particularly in favor of the original change, but at the time it was decided, there were few advocates for keeping 100+ commands in /usr/bin. There were several complaints about having that many commands, but chief amongst them was confusion for new users. By removing them from /usr/bin and providing an autocompletion script for bash that completes only a subset of the git subcommands, users will have fewer options to scan through—and to be scared of. The original plan called for moving the dash-style commands out, which has been done, but also eventually removing the links for any of the git-foo commands that are implemented in the core git binary. Over time, much of the functionality that was handled by external commands has migrated into the main git program. It is the eventual removal of the links that Hamano is asking about in his message, but much of the response was flames about the step already taken; some could not see any advantage to moving the git-foo commands out of /usr/bin. David Woodhouse is one of those who wants things to remain the same:
Just don't do it. Leave the git-foo commands as they were. They
weren't actually hurting anyone, and you don't actually _gain_
anything by removing them. For those occasional nutters who
_really_ care about the size of /usr/bin, give them the _option_
of a 'make install' without installing the aliases.
Several others agreed, but that particular horse had already left the barn. Throughout the thread, Linus Torvalds was increasingly strident about the $PATH-based workaround, which effectively ends the discussion that Hamano was trying to have. For that workaround to continue working, the links must be installed in /usr/libexec/git-core. Though it strays from the original intent, it is a reasonable compromise, one that will serve git-traditionalists as well as new users and others who no longer want the git-foo syntax. Two things have helped keep the controversy alive: some documentation, test, and example scripts still refer to dash-style commands, but worse than that, one must do man git-foo to get the man page for that subcommand. It is a convention within the Git community to use the dash style when referring to commands in text, which explains some of the usage. Because man requires a single argument, the dash style is used there as well, though git help foo is a reasonable alternative. For users who started relatively early with Git, and are aware of the dash style commands, these examples further muddy the water. It is a difficult problem. Projects must have room to change, but once users become used to a particular way of doing things, they will resist changing—sometimes quite loudly. As Petr "Pasky" Baudis points out, though, Git is still evolving:
You can't ask us to stop making any incompatible changes - Git is still
too young for that and it's UI got evolved, not designed. But we do
document the changes we do, even though we might do a better job
*spreading* the word.
The Git developers still see it as a young tool that may still undergo some fairly substantial modifications, while the hardcore users see it is a fixed tool that they use daily—or more frequently—to get work done. The tension between those two views is what leads to flamewars like we have seen here. Certainly the Git folks could have done a much better job in getting the word out—Hamano was looking for suggestions on how to do that better in his original post—but users are going to have to be flexible as well. (Log in to post comments)
I don't see the point Posted Sep 4, 2008 7:00 UTC (Thu) by dh (subscriber, #153) [Link]
Hi,
sorry, but I don't see the problem at all. Even though I only use git
At some places, I was bitten by change also. The solution was simple: I
Best regards,
I don't see the point Posted Sep 4, 2008 8:55 UTC (Thu) by nix (subscriber, #2304) [Link]
The moving-into-one-executable stuff has been happening for ages and is
not disrupted by having lots of names. All that happens is those names become symlinks to /usr/bin/git, which is sensitive to argv[0].
(Besides, there are *still* lots of names: they're just in a different
man pages Posted Sep 4, 2008 10:17 UTC (Thu) by mp (subscriber, #5615) [Link]
"Because man requires a single argument, the dash style is used there as well, though git help foo is a reasonable alternative."
For an ureasonable alternative the manual pages could be placed in a new "git" section (eg. /usr/share/man/mangit/foo.git.gz) and then "man git foo" would work.
Though I cannot believe I could even think of such an anti-FHS blasphemy :->
man pages Posted Sep 4, 2008 11:03 UTC (Thu) by epa (subscriber, #39769) [Link] For an ureasonable alternative the manual pages could be placed in a new "git" section (eg. /usr/share/man/mangit/foo.git.gz) and then "man git foo" would work.Darn it, what a fantastic idea! This would also work for perl and solve the ridiculous practice of putting Perl modules in section 1 of the manual. Didn't Tcl use to have /usr/share/man/man1tcl? What happened to that?
man pages Posted Sep 4, 2008 11:47 UTC (Thu) by mp (subscriber, #5615) [Link]
Going more off-topic.
In general manpages are put into the eight numbered sections and for disambiguation may have additional subsection/extension specified, so eg. Perl modules have their manpages named /usr/share/man/man3/Foo::Bar.3pm.gz
Now, there are some things which are distribution specific.
Of course none of these options looks as cool as man git foo.
man pages Posted Sep 4, 2008 16:56 UTC (Thu) by JoeBuck (subscriber, #2330) [Link] The eight numbered sections are an artifact of the organization of the original Unix manual, which Bell Labs would send you in book form because typesetting was not available to most users. And yes, I'm old enough to remember, I'm an old fart who used Version 7 Unix on a PDP-11.I hope we don't have to deal with that forever.
man pages Posted Sep 5, 2008 22:58 UTC (Fri) by giraffedata (subscriber, #1954) [Link] Man is obsolete in so many ways. Few parts of Unix have endured so long without upgrade. One problem, as has been pointed out, is its flatness, which not only makes it impossible to go right to information you want (you have to navigate through thousands of lines of the git "page" to find the subcommand you want, or else make git a hundred separate main commands), but also crowds the namespace. The fact that it can't get the text from the network also places it in olden times. There's lots of information you have to get today by browsing the web that would be much nicer via a quick shell command. And finally, the source is in the ancient nroff and troff languages, which are now unique to man. And don't hyperlink. I wrote a replacement almost 10 years ago that is based on Lynx and can find pages locally or on the web, in a hierarchical structure. (It works -- I use it exclusively for locally developed stuff). While I've watched more and more documentation move to the web, I haven't seen 'man' keep up with it. So it's actually getting harder to look something up.
man pages Posted Sep 6, 2008 3:39 UTC (Sat) by dlang (✭ supporter ✭, #313) [Link]
man's killer feature compared to your system is that it doesn't require network access to work.
man pages Posted Sep 6, 2008 14:47 UTC (Sat) by bronson (subscriber, #4806) [Link]
And that you can trivially search the entire topic (page). You ever try to find something in pinfo when you can't remember what page it's on? It gets tedious quick.
man pages Posted Sep 6, 2008 16:47 UTC (Sat) by paulj (subscriber, #341) [Link]
Try the 's' search, which searches the entire topic. Additionally, every GNU Info topic has an index page, which you can do a page-search in (the GNU 'info' viewer has a command specifically for searching the index, 'i', but pinfo doesn't seem to).
he GNU Info documentation format is pretty nice from the user's perspective (once you use pinfo), shame it never caught on outside of GNU. The Texinfo markup language for producing info docs has some quirks (e.g. having to escape full-stops in some situations), but those could probably be fixed.
man pages Posted Sep 6, 2008 16:55 UTC (Sat) by giraffedata (subscriber, #1954) [Link] [another killer feature that tradition man has that the proposed replacement doesn't is] that you can trivially search the entire topic (page). You ever try to find something in pinfo when you can't remember what page it's on? It gets tedious quick. You're referring to the fact that in these systems you can (and therefore do) break a manual up into subtopics such as a separate page per subcommand. (Though I haven't actually experienced it with pinfo; when I've used pinfo, the entire topic, e.g. GNU libc, has been one searchable unit). That's a good point, and one that has always bugged me about the worldwide web too. I don't suppose it would be hard to achieve that by having a browser function to combine the entire tree below the index page into a single document. Then you can still organize the documentation by directory hierarchy and provide direct access to a page, but also be able to browse the entire topic at once.
man pages Posted Sep 6, 2008 23:32 UTC (Sat) by bronson (subscriber, #4806) [Link]
Yes! It seems silly for every piece of documentation to have two links and two different representations: organized by section or all on one gigantic page.
That's really good to hear that Info allows you to search whole documents. Last I looked at Info (probably the late 90s), I feel like it could only search by the page you were on or the woefully incomplete indexes. Though, maybe it did, the memory is getting hazy... :)
man pages Posted Sep 6, 2008 16:29 UTC (Sat) by giraffedata (subscriber, #1954) [Link] man's killer feature compared to your system is that it doesn't require network access to work. My system has that feature. It requires network access only for documentation that is on the network (which is totally unreachable with traditional man). If you have "man pages" in /usr/man, my program reads them from there (still via Lynx, but with a file: URL).
man pages Posted Sep 6, 2008 8:42 UTC (Sat) by paulj (subscriber, #341) [Link] I wrote a replacement almost 10 years ago that is based on Lynx and can find pages locally or on the web, in a hierarchical structure.
You're describing the GNU info format and the Lynx-like 'pinfo' viewer. Try
man pages Posted Sep 6, 2008 17:12 UTC (Sat) by giraffedata (subscriber, #1954) [Link] You're describing the GNU info format ... Thanks for bringing that up. Info is evidence that almost 20 years ago people recognized that man was outdated. And I believe Info would have taken over the world except for the fact that the worldwide web followed closely on its heels, muted much of its value, and standardized a different markup language. GNU Info was a heavy influence for me in inventing my own replacement for man-style lookups, but its lack of network capability was the biggest weakness. Using an esoteric source language (compared to HTML) was the next biggest. And you can't do 'pinfo git foo' (hierarchical name space), can you?
man pages Posted Sep 6, 2008 23:28 UTC (Sat) by bronson (subscriber, #4806) [Link]
I'm not sure about that... I loathed info even before I really knew much about Archie or the WWW. It had some serious issues:
- It's manually laborious. With manpages, when you see an unrecognized keyword in a Bash script: 'man bash' /REPLY. Turnaround time two seconds. With info, you spend minutes clicking forward and back through a hierarchical structure of pages never knowing if you're hunting in the right place or not. The manpage will tell you instantly if the keyword is in the man documentation, info won't really.
- Info documentation tends to contain a lot more philosophical junk and background info that you need to sift through. I'm all for documenting that stuff, just make sure the reference docs come first!
- If you quit the info reader, it took a lot of effort to find your way back to where you were. With manpages, just '334G'.
- The original info reader was quite user-hostile. At least pinfo came along later.
So, I completely agree that manpages are really showing their age and that we need a better system. The system should be optimized for reference documentation though, not the lean-back, chopped up docs that Info, Gopher, Archie, and the WWW are built for.
man pages Posted Sep 6, 2008 23:48 UTC (Sat) by nix (subscriber, #2304) [Link]
info will instantly tell you if keywords are in the documentation. "i
KEYWORD" if there's an index (info documents have keyword indexes), "s KEYWORD" otherwise.
Most people's complaints about info boil down to "I don't know its
(What I really dislike is the way the info format ditches all the nice
man pages Posted Sep 4, 2008 13:16 UTC (Thu) by pj (subscriber, #4506) [Link]
I've always thought it was pretty cool that 'git foo --help' would pull up the man page. Yay unix!
man pages Posted Sep 5, 2008 23:29 UTC (Fri) by giraffedata (subscriber, #1954) [Link] I've always thought it was pretty cool that 'git foo --help' would pull up the man page. Yay unix! As a workaround by git develoeprs for the fact that you can't use the more logical command, 'help git foo', maybe. It's actually counter-Unix, as the Unix tradition is for --help to give you something more brief than a man page. And the Unix one-program-one-function rule says if you want to display a man page, you should invoke the man page displayer program, not the SCM access program. (That gives you the power to choose the man page displayer, etc.).
man pages Posted Sep 6, 2008 14:54 UTC (Sat) by bronson (subscriber, #4806) [Link]
> It's actually counter-Unix, as the Unix tradition is for --help to give you something more brief than a man page.
Absolutely true. It would be nice if each Git page started with a good synopsis and maybe a few examples. If those don't answer your questions, you can keep reading.
> And the Unix one-program-one-function rule says if you want to display a man page, you should invoke the man page displayer program, not the SCM access program.
This is only true for typical medium-complexity tools. Man is simply insufficient for more complex programs (most other scms, gdb, etc). At least Git still uses man! gdb and svn require you to use a different reader entirely.
Feature removal sparks Git flamewar Posted Sep 4, 2008 13:24 UTC (Thu) by rfunk (subscriber, #4054) [Link]
After years of using Subversion (and CVS before that), I've just recently
started dipping my toes into the git user pool, and the "git foo" vs "git-foo" difference has been an unnecessary stumbling block. In fact I didn't entirely grok until this article that they are (pre-1.6.0) exactly equivalent.
Moving consistently to a single form can only help user uptake.
Feature removal sparks Git flamewar Posted Sep 11, 2008 15:23 UTC (Thu) by engla (guest, #47454) [Link]
When this was planned, Linus came with a simple argument himself that basically puts it down. It's not so serious deep or earth-shattering: (approximate version follows)
"We have two interfaces, git-foo and git foo, and since aliases can only be called with the second form, and flags like --no-pager or --bare can only be used with the second form, the first form can never be the only one allowed"
That, combined with a will to have one and only one way to do it (usability) basically puts it down how it's going to be.
Git needs consistency, only then "normal" people can apprieciate its complexity.
|
|||||||||||||