Re: how to display file history?

[ebiederm@xmission.com (Eric W. Biederman)]

Linus Torvalds <torvalds@osdl.org> writes:

> On Mon, 15 May 2006, Eric W. Biederman wrote:
>> 
>> So that it has a chance of being remembered, and eventually fixed
>> the man pages of git-whatchanged and git-log only sort of tell you
>> that this is even possible.
>
> I don't think this is a man-page issue. I think this is a very basic 
> tutorial issue. 
>
> People still don't seem to realize how flexible (and powerful) the git 
> revision specifications are. It's not just limiting by path, all of these 
> work on _all_ of the "history tools" (whether they be gitk, qgit, "git 
> log", "git whatchanged" or your own home-cooked stuff):
>
>  - "revision based limiting"
>
> 	"a..b", but also "a ^b ^c ^d" or "a --not b c d" for the more 
> 	complex case where you're interested in one (or more) commit, but 
> 	not anything that flows from any of a number of other commits.
>
> 	"--all".
>
>  - "commit date based limiting"
>
> 	"--since=2.weeks.ago" "--since=aug.5th"
>
>  - "limit by number of hits"
>
> 	"-15"
>
>  - "limit by type or state"
>
> 	"--no-merges" and "--unpacked"
>
> And finally
>
>  - "limit by pathname"
>
> and you can combine all of these.
>
> So
>
> 	gitk --all --since=1.month -15 -- t/
>
> will show at most fifteen commits from _any_ branch that changed the 
> test subdirectory in the last month.
>
> And yeah, maybe that isn't a very interesting query, but it's easy to 
> explain and understand, so it's worth explaining early.
>
> And it should be equally obvious to everybody that if it works for "gitk", 
> that means that it works for "qgit", "git log" and "git whatchanged" too, 
> ie this is a very core concept, and not just some tacked-on thing for one 
> special tool.

Sure.  If it gets included in a tutorial is great, but existing
users aren't likely to read through a tutorial if they think they
know what is going on.

Having it documented in the man pages (i.e. the reference
documentation) which is where people look to check up on the fine
points of a command is more likely to matter.  Plus it doesn't
take any creativity to write a man page you just need to describe
what is, which makes man-pages easier to write than documentation
where you aren't certain of who your audience is.

Since it isn't specific to one command we probably need to document
the query limiting in a single file like the diff options are
and then just included it in all of the different man pages.

But regardless of where we put it, it needs to be documented someplace
besides in the email so you don't need to read the code to see that
the option is there. 

Eric