how to display file history?

how to display file history?

[Brown, Len]

it is tiresome to access kernel.org/git tree display
to see the list of commits that changed a particular file.
(and for files on my local disk, this isn't available).

How do I print the list of commits that change a particular file
on my local disk?

thanks,
-Len
 

Re: how to display file history?

[Shawn Pearce]

"Brown, Len" <len.brown@intel.com> wrote:
> it is tiresome to access kernel.org/git tree display
> to see the list of commits that changed a particular file.
> (and for files on my local disk, this isn't available).
> 
> How do I print the list of commits that change a particular file
> on my local disk?

I'm confused - why aren't these available on your local disk?  Do you
not have a clone of the kernel repository local?  If you don't have
a clone you aren't really going to be able to get a history.

But assuming you had one use whatchanged:

	git whatchanged A

will show only the commits which affected file A, listing them in
reverse order (most recent to oldest).

-- 
Shawn.

RE: how to display file history?

[Brown, Len]

 
>	git whatchanged A

thanks.  I've used this on entire repos before, but
for some reason didn't think of this command name
when looking for individual file history.

Searching git(7) for "history" didn't take me here.
Searching for "log" would have, but I must have
terminated that search when git-log and git-shortlog
turned out to not be what I was looking for.

-Len

Re: how to display file history?

[Junio C Hamano]

"Brown, Len" <len.brown@intel.com> writes:

>  
>>	git whatchanged A
>
> thanks.  I've used this on entire repos before, but
> for some reason didn't think of this command name
> when looking for individual file history.

Probably with recent enough git, one of

	git log --stat -- A
	git log -p -- A
	git log -p --full-diff -- A

might be more pleasant, depending on what you are trying to look
for.

"A" can be a single file, more than one files, a directory,...

Re: how to display file history?

[Linus Torvalds]

On Mon, 15 May 2006, Brown, Len wrote:
>
> it is tiresome to access kernel.org/git tree display
> to see the list of commits that changed a particular file.
> (and for files on my local disk, this isn't available).
> 
> How do I print the list of commits that change a particular file
> on my local disk?

Just do

	git whatchanged -p <file>

which has worked pretty much since day one. In fact, it's much better than 
that. The "file" can be any abritrary combination of files and/or 
directories, and it will track them all at the same time. So

	git whatchanged -p arch/ia64 include/asm-ia64

will track the ia64-specific changes.

Newer git versions (ie 1.3.x+) support this in "git log" too (it worked on 
older gits, but it was unacceptably slow, so you might as well consider it 
"nonworking"). So

	git log [-p] <filespec>

is your friend.

Finally, as usual, "gitk" is just a fancier log viewer. So just do

	gitk arch/ia64 include/asm-ia64

and enjoy.

You really shouldn't go to gitweb. The history view of gitweb is much less 
capable than any local view.

		Linus

Re: how to display file history?

[Eric W. Biederman]

Junio C Hamano <junkio@cox.net> writes:

> "Brown, Len" <len.brown@intel.com> writes:
>
>>  
>>>	git whatchanged A
>>
>> thanks.  I've used this on entire repos before, but
>> for some reason didn't think of this command name
>> when looking for individual file history.
>
> Probably with recent enough git, one of
>
> 	git log --stat -- A
> 	git log -p -- A
> 	git log -p --full-diff -- A
>
> might be more pleasant, depending on what you are trying to look
> for.
>
> "A" can be a single file, more than one files, a directory,...

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.  git-whatchanged is certainly worse,
but I don't think if I didn't know to look for it I could see the
fact that these commands take path names from looking at their
man pages.

Eric

Re: how to display file history?

[Linus Torvalds]

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.

			Linus

Re: how to display file history?

[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

Re: how to display file history?

[Linus Torvalds]

On Mon, 15 May 2006, Eric W. Biederman wrote:
>
> 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.

Somehow I really doubt that.

Check out the current man-page for "git log" or "git whatchanged".

In particular, check the "examples" section.

Yes, it's right there. And no, people apparently don't read the man-pages.

		Linus

Re: how to display file history?

[Marco Costalba]

>
> 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,

For qgit it doesn't work :-)

Well, it works but the nice boundary circles are not shown, and qgit
always adds  --boundary to command line args to feed git-rev-list, but
in this case it seems the --boundary option didn't do his job.

$git-rev-list --topo-order --boundary --parents --all --since=1.month -15 -- t/
ea892b27b15fbc46a3bb3ad2ddce737dc6590ae5
b0121fb3f279a9cf13aff9da060e742aef3a83fa
8d48ad62a902556b523ee892a3fbe4206d576d3f
8d48ad62a902556b523ee892a3fbe4206d576d3f
2c49009dbe98a26505891d3c680da73baf0b4f81
d14f776402d9f7040cc71ff6e3b992b2e019526a
b0121fb3f279a9cf13aff9da060e742aef3a83fa
7f498065e9bf85f6f3e954ec57dedf56fec29e01
6bd20358a9b831b3b545284188871bc844245c25
6bd20358a9b831b3b545284188871bc844245c25
9af0b8dbe2fb252262412a11254e2bcc6ffb87bb
7f498065e9bf85f6f3e954ec57dedf56fec29e01
c2b9e6994d044b218e59abf6d19f7751c4aa13e3
dd05ea1799656024a45017238bbd4857b5256370
c2b9e6994d044b218e59abf6d19f7751c4aa13e3
aadc81c13bbb103e7db759ba9a98a6f9509831f1
bd886fd3ea49b726493255d4adf5d20b31681713
aadc81c13bbb103e7db759ba9a98a6f9509831f1
42d0ee8302c361a0e3bde7bc59858eda94bc13a4
22293b9c41778bb60f3b07355e1b8e421a503702
2c49009dbe98a26505891d3c680da73baf0b4f81
143f4d94c6e2188a6bedfdfa268e66b579e3fbf9
dd05ea1799656024a45017238bbd4857b5256370
dd05ea1799656024a45017238bbd4857b5256370
fd60acaced6de16ebfb66959067e2b29f99a133e
143f4d94c6e2188a6bedfdfa268e66b579e3fbf9
2fc240a7b21c060529c1d2e19d6b483361f81f2a
22293b9c41778bb60f3b07355e1b8e421a503702
22293b9c41778bb60f3b07355e1b8e421a503702
83e77a25dc194933c0fb7908ab6d9fb84a5045e2
83e77a25dc194933c0fb7908ab6d9fb84a5045e2
2fa9a0fb31cbf01e8318a02c3e222d7fd3fd0a83
2fc240a7b21c060529c1d2e19d6b483361f81f2a
fd60acaced6de16ebfb66959067e2b29f99a133e
42d0ee8302c361a0e3bde7bc59858eda94bc13a4
42d0ee8302c361a0e3bde7bc59858eda94bc13a4
2fa9a0fb31cbf01e8318a02c3e222d7fd3fd0a83
fd60acaced6de16ebfb66959067e2b29f99a133e
bd886fd3ea49b726493255d4adf5d20b31681713
cf9dc65368113caa28f2829e2ada5477fbb031ec


       Marco

RE: how to display file history?

[Brown, Len]

>	git log --stat -- A

very handy indeed.

I was surprised on initial use that --stat is
limited to the file specified in "A" and doesn't
expand to describe the entire commit that touches "A".
(ie. the stat output is a subset of what is associated
with the displayed commit comments).

This, of course, is clear now, it just isn't what
I expected on first use.

thanks,
-Len

RE: how to display file history?

[Linus Torvalds]

On Mon, 15 May 2006, Brown, Len wrote:
>
> >	git log --stat -- A
> 
> very handy indeed.
> 
> I was surprised on initial use that --stat is
> limited to the file specified in "A" and doesn't
> expand to describe the entire commit that touches "A".
> (ie. the stat output is a subset of what is associated
> with the displayed commit comments).
> 
> This, of course, is clear now, it just isn't what
> I expected on first use.

Well,  you can obviously have your cake and eat it too (ie "--full-diff").

I don't often end up using the "--full-diff" thing. It's almost never 
actually worth it until I find the diff that I actually start caring 
about, and the full diff just makes it harder to see the part I explicitly 
told git I was interested in.

So the default "show only diffs for the files asked for" behaviour is in 
my opinion much superior (and it used to be the only one), because the 
"show the whole thing" part ends up being something you use only once 
you've already skimmed the default case and decide to go deeper.

Of course, "gitk" ends up using the full diff by default in its diff 
window. I'm not convinced that's the right thing, but usually when I use 
gitk I'm primarily looking at the history and the commit messages to 
decide if it's a relevant one, not the diff, so I don't think it matters.

			Linus

Re: how to display file history?

[J. Bruce Fields]

On Mon, May 15, 2006 at 10:29:20AM -0600, Eric W. Biederman wrote:
> 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.

Looks like the current git-log man page refers you to the git-rev-list
page for that, and the use of path names is documented there.

I think that's a pretty reasonable approach for reference
documentation, which should be concise.  Duplicating the git-rev-list
documentation (even some of it) to every man page to which it's relevant
would add a lot of text.

The current git-log man page is misleading, though--it suggests that
git-log accepts (and git-rev-list documents) only options, which might
discourage a reader from tracking down information about non-option
arguments.

I also agree about the tutorial--the "Keeping track of history" section
would be a good place to introduce this and git-grep with some fun
examples.  It's on my todo list, but may take a while, so maybe someone
else can beat me to it....

--b.

Re: how to display file history?

[Linus Torvalds]

On Mon, 15 May 2006, Marco Costalba wrote:
> 
> Well, it works but the nice boundary circles are not shown, and qgit
> always adds  --boundary to command line args to feed git-rev-list, but
> in this case it seems the --boundary option didn't do his job.

Well, it did do it's job, but you expected different counting priorities 
than git-rev-list actually gives you.

For the "limit by number" case, the commit counting counts _both_ 
"primary" commits and "boundary" commits, and will limit the total output 
to the number specified.

qgit would seem to prefer to have the commit counting only affect the 
"primary" commits, and not the "boundary" ones at all. Which might be 
sensible, but it's not the semantics it has now.

gitk doesn't care, because it uses the boundary commits just as hints.

I _think_ gitk is correct here, and qgit is being too strict in its 
semantic understanding of what the boundary commits mean. But I think so 
mostly because it would actually be pretty hard to do otherwise (ie the 
git-rev-list commit counting is largely defined by it's _implementation_, 
not necessarily by what you want it to do ;)

		Linus

Re: how to display file history?

[Marco Costalba]

On 5/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
>
>
> qgit would seem to prefer to have the commit counting only affect the
> "primary" commits, and not the "boundary" ones at all. Which might be
> sensible, but it's not the semantics it has now.
>
> gitk doesn't care, because it uses the boundary commits just as hints.
>

$ git-rev-list --topo-order --after="Apr 10" --before="Apr 11" HEAD |wc
     14      14     574
$ git-rev-list --topo-order --boundary --after="Apr 10" --before="Apr
11" HEAD |wc
     18      18     742

Boundary revisions in this case are _not_ passed through search
filtering. Using --boundary option we get revisions ouside given
filter range.

This does not apply to our previous example. So at least --boundary
behaviour it's a little bit inconsistent at the moment.

        Marco

Re: how to display file history?

[Linus Torvalds]

On Mon, 15 May 2006, Marco Costalba wrote:
> 
> $ git-rev-list --topo-order --after="Apr 10" --before="Apr 11" HEAD |wc
>     14      14     574
> $ git-rev-list --topo-order --boundary --after="Apr 10" --before="Apr
> 11" HEAD |wc
>     18      18     742
> 
> Boundary revisions in this case are _not_ passed through search
> filtering. Using --boundary option we get revisions ouside given
> filter range.

Right. And the commit counting is a special filter, and "boundary" is 
special in that it doesn't normally honor some other filters (it _does_ 
honor path-based ones, though, I think).

So you really should see "--boundary" as a heuristic, and as a hack to 
help you close the loop on uninteresting commits _faster_. But if 
something else has closed it for other reasons, you shouldn't depend on 
it.

		Linus

RE: how to display file history?

[Brown, Len]

 
>> >	git log --stat -- A
>> 
>> very handy indeed.
>> 
>> I was surprised on initial use that --stat is
>> limited to the file specified in "A" and doesn't
>> expand to describe the entire commit that touches "A".
>> (ie. the stat output is a subset of what is associated
>> with the displayed commit comments).
>> 
>> This, of course, is clear now, it just isn't what
>> I expected on first use.
>
>Well,  you can obviously have your cake and eat it too (ie 
>"--full-diff").
>
>I don't often end up using the "--full-diff" thing. It's almost never 
>actually worth it until I find the diff that I actually start caring 
>about, and the full diff just makes it harder to see the part 
>I explicitly told git I was interested in.

sounds good.

>So the default "show only diffs for the files asked for" 
>behaviour is in my opinion much superior (and it used to be the only
one),
>because the "show the whole thing" part ends up being something you use
only once 
>you've already skimmed the default case and decide to go deeper.

I agree.

>Of course, "gitk" ends up using the full diff by default in its diff 
>window. I'm not convinced that's the right thing, but usually 
>when I use gitk I'm primarily looking at the history and the commit
>messages to decide if it's a relevant one, not the diff, so I don't
think 
>it matters.

Yeah, I agree that gitk is fine how it is.

The only part I don't agree with above is the word "obviously".
'--full-diff --stats' didn't jump out at me from the man page.

To be fair, yes, I should probably take the time to read the docs
through
and not rely on the man pages, they've changed a lot since I last
looked.

-Len

Re: how to display file history?

[Jonas Fonseca]

Eric W. Biederman <ebiederm@xmission.com> wrote Mon, May 15, 2006:
> Linus Torvalds <torvalds@osdl.org> writes:
> 
> > On Mon, 15 May 2006, Eric W. Biederman wrote:
> > 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):
> >
> > [examples]
> 
> 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. 

I've put some of this on http://git.or.cz/gitwiki/RevisionSpecification
that for now may serve as an introduction ...

-- 
Jonas Fonseca