News for hackers. Stuff that matters.
Re:Git manpage generator by Xylakant on Thursday April 10, 2014 @12:56PM (#7567817)
actually, I don't care if git uses binary search or any other algorithm. I care that it helps me find bugs fast. There could be a "if you're interested in the tech" part in the git manpages that adds the information for the people that want or have to know, but I, as a user, couldn't care less - I can't change it anyways.
Re:Git manpage generator by wlesieutre on Thursday April 10, 2014 @03:25PM (#7569064)
To make the obligatory car analogy:

    git-car uses a synchronized system of pistons 
    and electrical arcs to extract energy from 
    hydrocarbon chains and convert it linear motion
Which is (a) what a car does, and (b) not how it's described in the car's manual.
Re:Git manpage generator by jimktrains2 on Thursday April 10, 2014 @03:59PM (#7569288)
Well, sort of. What happens when you run out of fuel (hydrocarbon or electric)? You have to know that it's a hydrocarbon-based engine, more so you need to know it's a spark-based engine (gasoline), not a pressure based engine (diesel), or even something else (CNG).

Also, if I want to get the most performance out of the car, or do something nonstandard, I need to know about the energy extraction process in order to pick better fuel or to adjust timings in the engine. (Sure most people won't, but if you want to, it's nice to have the information available).

Re:Git manpage generator by wlesieutre on Thursday April 10, 2014 @04:49PM (#7569607)
True, but cars deal with this by having separate manuals for normal owners and for maintenance. Owners usually need information like how often to change the oil and what pressure the tires should be at, but they're less likely to need engine timings.

Git's documentation (from what I hear, anyway, I've barely used it outside the GitHub client) seems like it's written to say "Everyone using git is a programmer, so everyone using git wants to know about git's implementation details."

As someone who would rather have a handle on the basics (and 99% of use cases) before digging into that, google does a better job at explaining what things are for. Which works, but I really wouldn't mind having some canonical user-friendly documentation available instantly on my computer.

Re:Git manpage generator by Xylakant on Thursday April 10, 2014 @04:18PM (#7569417)
No, I don't need to know the exact details of the engine. Your cars manual probably does not list the exact engine timings either. It says "fill in diesel here." If I want to tune my car I read the workshop manual, not the user manual. I totally support that the workshop manual exists, but git is lacking a users manual. I can explain my tester to run automatic tests, I can teach them git, but if I point any of them at the gut manual, I get a blank stars. It technobabble to them.
Re:Git manpage generator by edwintorok on Thursday April 10, 2014 @01:28PM (#7568122)
What matters is that 'git bisect' helps you find the bug in a significantly smaller number of steps than trying all revisions by hand. The manpage should definitely either mention the algorithm (binary search), or the reason why you would use it in the first place (it significantly reduces the number of steps until you find a bug, versus trying all commits). Note that the 'hg bisect' still fits this requirement, because its name hints at the algorithm.

If it only mentioned that it finds the changeset introducing a bug, without saying how, or that it does it efficiently what would be the reason to use the command at all?

Re:Git manpage generator by Xylakant on Thursday April 10, 2014 @04:14PM (#7569385)
Well, why not say "finds the rev in which a bug was introduces in an efficient way." Why bother me with further details? I don't care how - if the git team finds a better way to do it, fine.

A lot of potential git users won't be aware that binary search is what you want. You just lost those.