Updated Kernel Hacker's guide to git

Updated Kernel Hacker's guide to git

[Jeff Garzik]

I refreshed my git intro/cookbook for kernel hackers, at 
http://linux.yyz.us/git-howto.html

This describes most of the commands I use in day-to-day kernel hacking. 
  Let me know if there are glaring errors or missing key commands.

	Jeff

Re: Updated Kernel Hacker's guide to git

[Jay Cliburn]

Jeff Garzik wrote:
> I refreshed my git intro/cookbook for kernel hackers, at 
> http://linux.yyz.us/git-howto.html
> 
> This describes most of the commands I use in day-to-day kernel hacking. 
>  Let me know if there are glaring errors or missing key commands.

Thanks for doing this.  I've referred to your previous page rather often 
as I grope around trying to learn git and hack a vendor driver for 
submittal into the mainline kernel.

One thing that baffled me was how to use git to create a "kitchen sink" 
diff that would produce my entire driver suitable for submittal to lkml 
for review.  This probably isn't needed very often, but for new driver 
submittals it's important to know how to do it.  Francois Romieu showed 
me how (assume the new driver branch is named "driver"):

$ git diff $(git merge-base master driver)..driver

As a beginner, this command continues to be utterly non-intuitive to me, 
but it works.  There may be other ways to do it, too.

The point is, I think you should add instructions on your cookbook that 
address how to produce such a "kitchen sink" diff if you're submitting a 
brand new driver to lkml.  (Obviously I don't know what such a diff is 
actually called.)

Jay

Re: Updated Kernel Hacker's guide to git

[Martin Langhoff]

On 12/21/06, Jay Cliburn <jacliburn@bellsouth.net> wrote:
> $ git diff $(git merge-base master driver)..driver

There is a nicer way to do it with 1.4.x git -- note the 3 dots:

$ git diff master...driver

cheers,


martin

Re: Updated Kernel Hacker's guide to git

[Junio C Hamano]

"Martin Langhoff" <martin.langhoff@gmail.com> writes:

> On 12/21/06, Jay Cliburn <jacliburn@bellsouth.net> wrote:
>> $ git diff $(git merge-base master driver)..driver
>
> There is a nicer way to do it with 1.4.x git -- note the 3 dots:
>
> $ git diff master...driver

Careful.

I think Jay was looking at this kind of ancestry graph:

         *---*---*---* driver
        /
 --o---o---x---x---x---x master

There might be quite a few merges on either side, but the point
is '*' are not yet 'in', and 'o' and 'x' are already in the
'upstream (but 'x' are not in Jay's driver yet).

The three dots would give both '*' and 'x'; I do not think that
is what Jay wants.  A submitter to mainline usually wants only
'*' commits.

I've always thought that 'submission' is supposed to be done as
a series of patches, in which case a reasonable way would be to
do:

	git format-patch -n master driver

If on the other hand a single roll-up patch is desired, I think
the most reasonable thing to do is to first merge the tip of the
master to the tip of driver, resolve all the conflicts as
needed, and take the diff between the 'master' and the result:


         *---*---*---*---y driver (y is the test merge)
        /               / 
 --o---o---x---x---x---x master

	git checkout driver
        git merge master
	... resolve conflicts if any, then "git commit"
	git diff master

This diff by definition should apply cleanly to the tip of
'master' and would result in the source that contains the
updates for the driver.

When you are done, it would be advisable to do:

	git reset --hard HEAD^

to remove that 'y' merge, unless the merge involved a true
conflict resolution.

Re: Updated Kernel Hacker's guide to git

[Linus Torvalds]

On Wed, 20 Dec 2006, Jay Cliburn wrote:
> 
> $ git diff $(git merge-base master driver)..driver

Be careful. This ONLY works if you don't have criss-cross merges etc, so 
you need to be somewhat careful about it. If you end up having a complex 
merge history between the origin branch and your development tree, things 
will stop working

So it's actually worth understanding what the above does.

Here's the picture to keep in mind: you started off with something like 
this:

	<- older			newer ->

	..--A---B---C---D

where the top commit was D, and you started doing your own work off there. 
However, the tree you are tracking (doing "git fetch origin" or somethng) 
ALSO continues, so soon enough you'll have a history that looks like

	<- older			newer ->

	..--A---B---C---D---E---F---G---H <-"origin"
	                 \
	                  --X---Y---Z <- your "driver" branch"

where your work is the "X-Y-Z" sequence.

How, the reason you must NOT do

	git diff origin..driver

or something like that, is that it will LITERALLY do a diff between those 
two heads. And while that is a perfectly normal diff, it's not what you 
want: it's the diff between the up-stream work and yours, and it will show 
that a lot of work has _not_ happened in your branch (all the E-F-G-H 
stuff), and then you've added some work (X-Y-Z).

What you obviously WANT to have is the "diff" between "D" (which was the 
point where you started) and "Z" (which is where you are now. That's what 
you want to send up-stream.

Now, the way people used to do this under CVS, was to simply _remember_ D. 
Preferably by doing a tag at the point where they started working. Then 
you can always diff against that tag.

You can do that in git too, of course, but it would just be stupid. 
Because git actually _knows_ the history, so you can just ask git

	"What is the most recent commit that both 'origin' and 'driver'
	 have in common?"

the answer, of course, is the very commit you want: D. And how do you ask 
for that "most recent common commit"? That's right: it's called the "merge 
base", because it's also the thing you'd use as the base in a bog-standard 
three-way merge.

So "git merge-base origin driver" just returns "D", without you having had 
to tag it or remember it at all.

So when you do

	git diff $(git merge-base origin driver)..driver

you're literally asking for the diff between your current top of the 
"driver" branch, and the place where you diverged from "origin".

Now, why do I mention the fact that THIS DOES NOT WORK if you do merges 
and you no longer have a linear tree? Think about it. If you actually ever 
pull on the up-stream and create a merge in your development tree, the 
commit history graph will now look something like this:

	<- older			newer ->

	..--A---B---C---D---E---F---G---H <-"origin"
	                 \        \
	                  --X---Y--M--Z <- your "driver" branch"

where the "M" commit is because you merged some new work from origin.

But see what that did to the most recent commit? Now, the most recent 
commit is no longer "D". In fact, it's not even your "merge" commit, if 
you think about it (even though you might naively think so), because that 
merge commit doesn't even exist in "origin", so clearly it cannot be the 
most recent common commit.

The most recent commit in common is "F". So now,

	git diff $(git merge-base origin driver)..driver

will give the difference between _F_ and your current tip Z.

The thing is, THIS IS STILL THE RIGHT THING TO DO. It's magic. Since you 
did a merge in M, all the things up until F have been merged into Z too, 
so you actually NO LONGER want to diff against D. Nor do you want to diff 
against M (since that would mean that you would not see the work you did 
in X and Y). 

By doing a diff against F (and your own merge having done the right 
thing), you actually end up getting the "union" of work for X-Y-Z when you 
do that magic command line.  If you had done it against D, you'd have seen 
the work in E and F that the merge M brought in - but you don't want that, 
because you want just the work YOU did, not anything in "origin".

So what you want is actually exactly again the most recent common commit.

HOWEVER. While it magically "just works" in things like this, it doesn't 
actually work for the really complex cases. If I've merged an eariler 
version of your work AND you did a merge from me too, you can have a 
criss-cross merge where there simply isn't one "most recent common commit" 
at all any more, but two or more. And then you really do need to do more.

This is one reason why I suggest developers not merge from me very often: 
if your development tree is just a straight line (ie you only had that one 
merge), you can't ever even get in that situation, and perhaps as 
importantly, if/when I pull from you, the result will also tend to look 
more understandable to people who look at the history.

But another way to avoid a criss-cross merge is actually to never let me 
see your tree at all, and then you can merge with me as often as you damn 
well like. And in that case, the magic

	git diff $(git merge-base origin driver)..driver

is always going to give you exactly what you want. You can use merges to 
keep up-to-date, and always see what you want to send off by email 
upstream. The history will look like crap (you'll end up having a ton of 
merges in your tree), but if you aren't going to publicise your history 
anyway (just the diff end result), why would you care?

(And yes, you can actually do "git diff origin...driver" with _three_ 
dots. I'm not even going to explain _why_ that works, because that's a 
whole other kettle of fish, and is actually a magic special case in 
builtin-diff.c. So feel free to use it because it's short and sweet, but 
the long format is actually easier to explain what it actually MEANS).

		Linus

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Jay Cliburn wrote:
> Jeff Garzik wrote:
>> I refreshed my git intro/cookbook for kernel hackers, at 
>> http://linux.yyz.us/git-howto.html
>>
>> This describes most of the commands I use in day-to-day kernel 
>> hacking.  Let me know if there are glaring errors or missing key 
>> commands.
> 
> Thanks for doing this.  I've referred to your previous page rather often 
> as I grope around trying to learn git and hack a vendor driver for 
> submittal into the mainline kernel.
> 
> One thing that baffled me was how to use git to create a "kitchen sink" 
> diff that would produce my entire driver suitable for submittal to lkml 
> for review.  This probably isn't needed very often, but for new driver 
> submittals it's important to know how to do it.  Francois Romieu showed 
> me how (assume the new driver branch is named "driver"):
> 
> $ git diff $(git merge-base master driver)..driver
> 
> As a beginner, this command continues to be utterly non-intuitive to me, 
> but it works.  There may be other ways to do it, too.
> 
> The point is, I think you should add instructions on your cookbook that 
> address how to produce such a "kitchen sink" diff if you're submitting a 
> brand new driver to lkml.  (Obviously I don't know what such a diff is 
> actually called.)

You inflict upon yourself all sorts of pain if you keep updating 
'master', but don't merge that into 'driver'.  Typically you want to 
rebase after updating master:

	git checkout driver
	git rebase master
	# build and test
	git prune

or merge master into your current branch:

	git checkout driver
	git pull . master
	# build and test

That way, you are GUARANTEED that

	git diff master..driver

will result in a diff that you can send upstream.

One moral of this story, as (I think) Linus mentioned, don't update 
'master' too frequently.  That's one key lesson of distributed 
programming.  Unless the upstream kernel has a key API change or bug fix 
you need, just pretend the outside world does not exist, and hack away 
on your driver.

	Jeff

Re: Updated Kernel Hacker's guide to git

[Willy Tarreau]

Hi Jeff !

On Wed, Dec 20, 2006 at 10:04:17PM -0500, Jeff Garzik wrote:
> I refreshed my git intro/cookbook for kernel hackers, at 
> http://linux.yyz.us/git-howto.html

Thanks for this update, it was my most useful source of inspiration
when I started with git.

> This describes most of the commands I use in day-to-day kernel hacking. 
>  Let me know if there are glaring errors or missing key commands.

I very often use "git-format-patch -k -m" to produce individual patches
that I delay, merge in other branches, or even in other trees with
"git-am -k -3".  I believe it was Davem who suggested this a while ago,
and I agree it's very convenient to maintain a patch collection (and
sometimes to clean them up).

Also, I think that for beginners, you have not insisted enough on the
fact that they should not modify the master branch, but that they
should immediately create their own branch before any local changes.

I got caught by this when I started, and had trouble playing with the
origin branch to try to fix my mistakes.

Overall it's a good tutorial anyway.

Cheers,
Willy

Re: Updated Kernel Hacker's guide to git

[Nigel Cunningham]

Hi.

On Wed, 2006-12-20 at 22:04 -0500, Jeff Garzik wrote:
> I refreshed my git intro/cookbook for kernel hackers, at 
> http://linux.yyz.us/git-howto.html
> 
> This describes most of the commands I use in day-to-day kernel hacking. 
>   Let me know if there are glaring errors or missing key commands.

Thanks for the work! I'd suggest also saying how to repack and cleanup.
Could also be a good idea to go through the steps for uploading to
master.kernel.org or elsewhere?

Regards,

Nigel

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Nigel Cunningham wrote:
> Hi.
> 
> On Wed, 2006-12-20 at 22:04 -0500, Jeff Garzik wrote:
>> I refreshed my git intro/cookbook for kernel hackers, at 
>> http://linux.yyz.us/git-howto.html
>>
>> This describes most of the commands I use in day-to-day kernel hacking. 
>>   Let me know if there are glaring errors or missing key commands.
> 
> Thanks for the work! I'd suggest also saying how to repack and cleanup.

Yes, I should mention repacking.  When you say cleanup, what 
specifically do you mean?


> Could also be a good idea to go through the steps for uploading to
> master.kernel.org or elsewhere?

Yes, push should be mentioned at the very least.

	Jeff

Re: Updated Kernel Hacker's guide to git

[Nigel Cunningham]

Hi.

On Thu, 2006-12-21 at 06:44 -0500, Jeff Garzik wrote:
> Nigel Cunningham wrote:
> > Hi.
> > 
> > On Wed, 2006-12-20 at 22:04 -0500, Jeff Garzik wrote:
> >> I refreshed my git intro/cookbook for kernel hackers, at 
> >> http://linux.yyz.us/git-howto.html
> >>
> >> This describes most of the commands I use in day-to-day kernel hacking. 
> >>   Let me know if there are glaring errors or missing key commands.
> > 
> > Thanks for the work! I'd suggest also saying how to repack and cleanup.
> 
> Yes, I should mention repacking.  When you say cleanup, what 
> specifically do you mean?

Oh, I was just thinking of the related commands - prune-packed,
count-objects, fsck-objects and so on. (I know repack does prune-packed
when you use -d, but it might be handy to mention it anyway... or
not :>)

> > Could also be a good idea to go through the steps for uploading to
> > master.kernel.org or elsewhere?
> 
> Yes, push should be mentioned at the very least.

Nigel

Re: Updated Kernel Hacker's guide to git

[Francois Romieu]

Jeff Garzik <jeff@garzik.org> :
> I refreshed my git intro/cookbook for kernel hackers, at 
> http://linux.yyz.us/git-howto.html
> 
> This describes most of the commands I use in day-to-day kernel hacking. 
>  Let me know if there are glaring errors or missing key commands.

o 'git whatchanged shnortz' can probably be replaced with
  'git log -- schnortz' so there is one command less to remember.

o "Display changes since last git-update-index:"
  Fine but you have not told the reader what git-update-index is.

-- 
Ueimor

Re: Updated Kernel Hacker's guide to git

[Guennadi Liakhovetski]

On Wed, 20 Dec 2006, Jeff Garzik wrote:

> I refreshed my git intro/cookbook for kernel hackers, at
> http://linux.yyz.us/git-howto.html

Very nice, thanks! A couple of remarks from an absolute git newbie:

1. I heard "git am" is supposed to supersede apply-mbox

2. What I often have problems with is - what to do if git spits at me a 
bunch of conflict messages after a seemingly safe pull or similar. Don't 
know if you want to cover those points but "git troubleshooting" would 
definitely be a valuable document.

Thanks
Guennadi
---
Guennadi Liakhovetski

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Guennadi Liakhovetski wrote:
> On Wed, 20 Dec 2006, Jeff Garzik wrote:
> 
>> I refreshed my git intro/cookbook for kernel hackers, at
>> http://linux.yyz.us/git-howto.html
> 
> Very nice, thanks! A couple of remarks from an absolute git newbie:
> 
> 1. I heard "git am" is supposed to supersede apply-mbox

Hey, that's pretty neat.  Glad you told me, this should improve my 
workflow a bit.


> 2. What I often have problems with is - what to do if git spits at me a 
> bunch of conflict messages after a seemingly safe pull or similar. Don't 
> know if you want to cover those points but "git troubleshooting" would 
> definitely be a valuable document.

Agreed.

	Jeff

Re: Updated Kernel Hacker's guide to git

[Jesper Juhl]

On 21/12/06, Jeff Garzik <jeff@garzik.org> wrote:
> I refreshed my git intro/cookbook for kernel hackers, at
> http://linux.yyz.us/git-howto.html
>
> This describes most of the commands I use in day-to-day kernel hacking.
>   Let me know if there are glaring errors or missing key commands.
>
Very nice.

A bit on how to revert a commit and how to rebase a branch would make
it even nicer :)

Thank you for a very good document, Jeff.

-- 
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

Re: Updated Kernel Hacker's guide to git

[Horst H. von Brand]

Jeff Garzik <jeff@garzik.org> wrote:
> I refreshed my git intro/cookbook for kernel hackers, at
> http://linux.yyz.us/git-howto.html

Looks nice, starting to look it over.

Notes:

Getting started:

  There are RPM packages available (I think they are for latest Fedora; in
  case of doubt get the latest SRPM and build yourself, sometimes the
  distros lag /way/ behind). There are also Debian packages there, dunno
  about those.

Basic tasks:

  'git pull' should be enough, no need to give the URL each time.
  It is useful to tell people how to get "nonofficial" branches (via URL +
  branches) too.
  

Miscellaneous debris:

  'git pull' has gotten tags each time for me?
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Updated Kernel Hacker's guide to git

[Jeff Garzik]

Another year, another update!  :)

The kernel hacker's guide to git has received some updates:

	http://linux.yyz.us/git-howto.html

This includes all the input sent to me in the past several months, as 
well as a few new tips and tricks I use on a regular basis.

In general, this document is designed to be a quick-start cookbook, and 
not a comprehensive introduction.

Merry Christmas and Happy Holidays to all!

	Jeff

Re: Updated Kernel Hacker's guide to git

[Robert P. J. Day]

On Sun, 23 Dec 2007, Jeff Garzik wrote:

> Another year, another update!  :)
>
> The kernel hacker's guide to git has received some updates:
>
> 	http://linux.yyz.us/git-howto.html
>
> This includes all the input sent to me in the past several months,
> as well as a few new tips and tricks I use on a regular basis.
>
> In general, this document is designed to be a quick-start cookbook,
> and not a comprehensive introduction.

there's one issue i have with this document, and that's that i wish it
more carefully distinguished between regular git "user" tasks, and git
"developer" tasks.

i may be mistaken, but it would seem that a lot of folks are going to
be what i call basic users, who only want to update their git tree,
check the logs, check the status and so on.  and if they start to get
ambitious, they might make some changes to the tree, do a diff, and
submit a patch.  but in the beginning, they won't be making commits or
switching branches, etc.

in short, i can see the value of something like a "getting started
with git as a basic user" tutorial.  does such a thing exist?

rday
--

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Robert P. J. Day wrote:
> On Sun, 23 Dec 2007, Jeff Garzik wrote:
> 
>> Another year, another update!  :)
>>
>> The kernel hacker's guide to git has received some updates:
>>
>> 	http://linux.yyz.us/git-howto.html
>>
>> This includes all the input sent to me in the past several months,
>> as well as a few new tips and tricks I use on a regular basis.
>>
>> In general, this document is designed to be a quick-start cookbook,
>> and not a comprehensive introduction.
> 
> there's one issue i have with this document, and that's that i wish it
> more carefully distinguished between regular git "user" tasks, and git
> "developer" tasks.
> 
> i may be mistaken, but it would seem that a lot of folks are going to
> be what i call basic users, who only want to update their git tree,
> check the logs, check the status and so on.  and if they start to get
> ambitious, they might make some changes to the tree, do a diff, and
> submit a patch.  but in the beginning, they won't be making commits or
> switching branches, etc.
> 
> in short, i can see the value of something like a "getting started
> with git as a basic user" tutorial.  does such a thing exist?


hmmm.  There's the tutorial linked at the bottom of the page, which in 
turn links to http://www.kernel.org/pub/software/scm/git/docs/everyday.html

git is a developer's tool, so I sorta targetted that audience.  I 
definitely agree that is not only git audience...

	Jeff

Re: Updated Kernel Hacker's guide to git

[Robert P. J. Day]

On Sun, 23 Dec 2007, Jeff Garzik wrote:

> Robert P. J. Day wrote:
> > On Sun, 23 Dec 2007, Jeff Garzik wrote:
> >
> > > Another year, another update!  :)
> > >
> > > The kernel hacker's guide to git has received some updates:
> > >
> > > 	http://linux.yyz.us/git-howto.html
> > >
> > > This includes all the input sent to me in the past several months,
> > > as well as a few new tips and tricks I use on a regular basis.
> > >
> > > In general, this document is designed to be a quick-start cookbook,
> > > and not a comprehensive introduction.
> >
> > there's one issue i have with this document, and that's that i wish it
> > more carefully distinguished between regular git "user" tasks, and git
> > "developer" tasks.
> >
> > i may be mistaken, but it would seem that a lot of folks are going to
> > be what i call basic users, who only want to update their git tree,
> > check the logs, check the status and so on.  and if they start to get
> > ambitious, they might make some changes to the tree, do a diff, and
> > submit a patch.  but in the beginning, they won't be making commits or
> > switching branches, etc.
> >
> > in short, i can see the value of something like a "getting started
> > with git as a basic user" tutorial.  does such a thing exist?
>
> hmmm.  There's the tutorial linked at the bottom of the page, which
> in turn links to
> http://www.kernel.org/pub/software/scm/git/docs/everyday.html
>
> git is a developer's tool, so I sorta targetted that audience.  I
> definitely agree that is not only git audience...

just to be clear, i'm not complaining about the quality of the
document above, but when i got started with git, what i really wanted
was a list of what i (as a simple, non-developer user) could do once i
cloned a repository.

to that end, i put together my own little reference list of git
commands.  for example, i collected ways to examine my repository --
git commands like branch, tag, log/shortlog, what-changed, show, grep,
blame, that sort of thing.  exactly the kind of stuff a new user might
want to know about, even without the ability to change anything.

just my $0.02.

rday
--

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: Updated Kernel Hacker's guide to git

[Dieter Ries]

Robert P. J. Day schrieb:
> On Sun, 23 Dec 2007, Jeff Garzik wrote:
> 
>> Robert P. J. Day wrote:
>>> On Sun, 23 Dec 2007, Jeff Garzik wrote:
>>>
>>>> Another year, another update!  :)
>>>>
>>>> The kernel hacker's guide to git has received some updates:
>>>>
>>>> 	http://linux.yyz.us/git-howto.html
>>>>
>>>> This includes all the input sent to me in the past several months,
>>>> as well as a few new tips and tricks I use on a regular basis.
>>>>
>>>> In general, this document is designed to be a quick-start cookbook,
>>>> and not a comprehensive introduction.
>>> there's one issue i have with this document, and that's that i wish it
>>> more carefully distinguished between regular git "user" tasks, and git
>>> "developer" tasks.
>>>
>>> i may be mistaken, but it would seem that a lot of folks are going to
>>> be what i call basic users, who only want to update their git tree,
>>> check the logs, check the status and so on.  and if they start to get
>>> ambitious, they might make some changes to the tree, do a diff, and
>>> submit a patch.  but in the beginning, they won't be making commits or
>>> switching branches, etc.
>>>
>>> in short, i can see the value of something like a "getting started
>>> with git as a basic user" tutorial.  does such a thing exist?
>> hmmm.  There's the tutorial linked at the bottom of the page, which
>> in turn links to
>> http://www.kernel.org/pub/software/scm/git/docs/everyday.html
>>
>> git is a developer's tool, so I sorta targetted that audience.  I
>> definitely agree that is not only git audience...
> 
> just to be clear, i'm not complaining about the quality of the
> document above, but when i got started with git, what i really wanted
> was a list of what i (as a simple, non-developer user) could do once i
> cloned a repository.
> 
> to that end, i put together my own little reference list of git
> commands.  for example, i collected ways to examine my repository --
> git commands like branch, tag, log/shortlog, what-changed, show, grep,
> blame, that sort of thing.  exactly the kind of stuff a new user might
> want to know about, even without the ability to change anything.

Could you perhaps publish your reference list as kind of a christmas
gift to all basic users like me?


cu
Dieter

ps.: sorry for sending this twice, messed up recipients.
> 
> just my $0.02.
> 
> rday
> --
> 
> ========================================================================
> Robert P. J. Day
> Linux Consulting, Training and Annoying Kernel Pedantry
> Waterloo, Ontario, CANADA
> 
> http://crashcourse.ca
> ========================================================================
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 

Re: Updated Kernel Hacker's guide to git

[Robert P. J. Day]

On Sun, 23 Dec 2007, Dieter Ries wrote:

> Robert P. J. Day schrieb:

> > just to be clear, i'm not complaining about the quality of the
> > document above, but when i got started with git, what i really
> > wanted was a list of what i (as a simple, non-developer user)
> > could do once i cloned a repository.
> >
> > to that end, i put together my own little reference list of git
> > commands.  for example, i collected ways to examine my repository
> > -- git commands like branch, tag, log/shortlog, what-changed,
> > show, grep, blame, that sort of thing.  exactly the kind of stuff
> > a new user might want to know about, even without the ability to
> > change anything.
>
> Could you perhaps publish your reference list as kind of a christmas
> gift to all basic users like me?

if you give me a day or two (or three), i may put an updated version
of that up on my wiki.

rday

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: Updated Kernel Hacker's guide to git

[Stefan Richter]

Dieter Ries wrote:
> Robert P. J. Day schrieb:
>> when i got started with git, what i really wanted
>> was a list of what i (as a simple, non-developer user) could do once i
>> cloned a repository.
>>
>> to that end, i put together my own little reference list of git
>> commands.  for example, i collected ways to examine my repository --
>> git commands like branch, tag, log/shortlog, what-changed, show, grep,
>> blame, that sort of thing.  exactly the kind of stuff a new user might
>> want to know about, even without the ability to change anything.
> 
> Could you perhaps publish your reference list as kind of a christmas
> gift to all basic users like me?

Here are three out of four things which I do frequently with git repos:
I look at

  - commits and blobs in other people's trees with gitweb,

  - commits in a local tree with gitk,

  - specific changes to source code with qgit, using it as "git blame"
    GUI.

(The fourth thing is feeding a driver subsystem git tree at kernel.org
using a minimum number of git commands.  Everything else which I do with
git I do so infrequently that I have to reread manuals all the time.)
-- 
Stefan Richter
-=====-=-=== ==-- =-===
http://arcgraph.de/sr/

Re: Updated Kernel Hacker's guide to git

[Robert P. J. Day]

On Sun, 23 Dec 2007, Dieter Ries wrote:

> Could you perhaps publish your reference list as kind of a christmas
> gift to all basic users like me?

FYI, i'm typing in my own reference list as we speak here:

  http://www.crashcourse.ca/wiki/index.php/Git

still quite a bit to go, but you can get the overall idea.  new
sections should be appearing there as the morning progresses.

rday

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: Updated Kernel Hacker's guide to git

[WANG Cong]

On Sun, Dec 23, 2007 at 06:13:03AM -0500, Jeff Garzik wrote:
>Another year, another update!  :)
>
>The kernel hacker's guide to git has received some updates:
>
>	http://linux.yyz.us/git-howto.html
>
>This includes all the input sent to me in the past several months, as 
>well as a few new tips and tricks I use on a regular basis.
>
>In general, this document is designed to be a quick-start cookbook, and 
>not a comprehensive introduction.


Jeff, very good! I like it. Thank you! ;-)

>
>Merry Christmas and Happy Holidays to all!
>

Merry Christmas, kernel hackers!

Best wishes!

Re: Updated Kernel Hacker's guide to git

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 418 bytes --]

On Sun, Dec 23, 2007 at 06:13:03AM -0500, Jeff Garzik <jeff@garzik.org> wrote:
> Another year, another update!  :)
> 
> The kernel hacker's guide to git has received some updates:
> 
> 	http://linux.yyz.us/git-howto.html

one minor note:

i would suggest using:

$ git shortlog master..HEAD

instead of

$ git log master..HEAD | git shortlog

to avoid unnecessary complexity :)

thanks,
- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Updated Kernel Hacker's guide to git

[Salikh Zakirov]

Jeff Garzik wrote:
> The kernel hacker's guide to git has received some updates: 
> http://linux.yyz.us/git-howto.html

I have some comments on the contents, though  I need to warn, 
that  I've been following git development for about year and a half now,
and I am not a kernel hacker, so my comments may have wrong bias.

>     Obtain a diff between current branch, and master branch
> 
> In most trees with branches, .git/refs/heads/master contains the
> current 'vanilla' upstream tree, for easy diffing and merging. (in
> trees without branches, 'master' simply contains your latest changes)
> 
> $ git diff master..HEAD

IMHO, syntax 'git diff master HEAD' is preferable, in order to avoid
confusion with 'git log master..HEAD' usage, which has quite different
meaning, roughly expressible as

  git diff `git merge-base master HEAD` HEAD

for getting one big diff of the changes in HEAD since master)

> (this is equivalent to git diff HEAD, when used with HEAD branch)

This seems incorrect to me, as 'git diff master HEAD' compares two
revisions, while 'git diff HEAD' compares working tree with HEAD revision.

Besides, expression 'HEAD branch' is misleading, because HEAD is not a branch by itself,
but rather a link to the latest state of the current branch.

Re: Updated Kernel Hacker's guide to git

[Jan Engelhardt]

On Dec 23 2007 06:13, Jeff Garzik wrote:
> Another year, another update!  :)
>
> The kernel hacker's guide to git has received some updates:
>
> 	http://linux.yyz.us/git-howto.html
>

It says

"""Don't forget to download tags from time to time.

git pull only downloads sha1-indexed object data, and the requested
remote head. This misses updates to the .git/refs/tags/ and
.git/refs/heads/ directories. For tags, run git fetch --tags $URL."""


But when I do git pull on a simple tracking tree (e.g. git-clone
torvalds/linux-2.6.git; git pull;) it automatically grabs new tags.

Re: Updated Kernel Hacker's guide to git

[Stefan Richter]

Jan Engelhardt wrote:
>> 	http://linux.yyz.us/git-howto.html
> 
> It says
> 
> """Don't forget to download tags from time to time.
> 
> git pull only downloads sha1-indexed object data, and the requested
> remote head. This misses updates to the .git/refs/tags/ and
> .git/refs/heads/ directories. For tags, run git fetch --tags $URL."""
> 
> But when I do git pull on a simple tracking tree (e.g. git-clone
> torvalds/linux-2.6.git; git pull;) it automatically grabs new tags.

A while ago the default behavior of git pull was changed to fetch all
tags which point to objects that can be reached from any of the tracked
heads.

Old behaviour:  Option --tags was needed to fetch tags at all.  Current
behavior:  Option --tags forces to download all tags and the objects
they point to.  Option --no-tags works like the old default behavior.

Readers of Kernel Hackers' Guide to git will most certainly have a
recent enough version of git so that the "download_tags" subsection can
be removed without replacement.
-- 
Stefan Richter
-=====-=-=== ==-- =====
http://arcgraph.de/sr/

Re: Updated Kernel Hacker's guide to git

[Junio C Hamano]

Stefan Richter <stefanr@s5r6.in-berlin.de> writes:

> Jan Engelhardt wrote:
>>> 	http://linux.yyz.us/git-howto.html
>> 
>> It says
>> 
>> """Don't forget to download tags from time to time.
>> 
>> git pull only downloads sha1-indexed object data, and the requested
>> remote head. This misses updates to the .git/refs/tags/ and
>> .git/refs/heads/ directories. For tags, run git fetch --tags $URL."""
>> 
>> But when I do git pull on a simple tracking tree (e.g. git-clone
>> torvalds/linux-2.6.git; git pull;) it automatically grabs new tags.
>
> A while ago the default behavior of git pull was changed to fetch all
> tags which point to objects that can be reached from any of the tracked
> heads.
>
> Old behaviour:  Option --tags was needed to fetch tags at all.  Current
> behavior:  Option --tags forces to download all tags and the objects
> they point to.  Option --no-tags works like the old default behavior.
>
> Readers of Kernel Hackers' Guide to git will most certainly have a
> recent enough version of git so that the "download_tags" subsection can
> be removed without replacement.

All correct.

That "A while ago" is quite a while ago, though.  IIRC it was
added very early in 2006, which is eons ago in git timescale.

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Stefan Richter wrote:
> Jan Engelhardt wrote:
>>> 	http://linux.yyz.us/git-howto.html
>> It says
>>
>> """Don't forget to download tags from time to time.
>>
>> git pull only downloads sha1-indexed object data, and the requested
>> remote head. This misses updates to the .git/refs/tags/ and
>> .git/refs/heads/ directories. For tags, run git fetch --tags $URL."""
>>
>> But when I do git pull on a simple tracking tree (e.g. git-clone
>> torvalds/linux-2.6.git; git pull;) it automatically grabs new tags.
> 
> A while ago the default behavior of git pull was changed to fetch all
> tags which point to objects that can be reached from any of the tracked
> heads.


This does not work in all cases.  When I retrieve the latest kernel, it 
downloads the tags:

	cd /spare/repo/linux-2.6
	git pull

but when I pull those changes into another local repo, the tags do -not- 
follow the objects:

	cd /spare/repo/misc-2.6
	git checkout master
	git pull ../linux-2.6
	git fetch --tags ../linux-2.6	# still required to this day

Regards,

	Jeff

Re: Updated Kernel Hacker's guide to git

[Stefan Richter]

Jeff Garzik wrote:
> Stefan Richter wrote:
>> A while ago the default behavior of git pull was changed to fetch all
>> tags which point to objects that can be reached from any of the tracked
>> heads.
> 
> 
> This does not work in all cases.  When I retrieve the latest kernel, it 
> downloads the tags:
> 
>     cd /spare/repo/linux-2.6
>     git pull
> 
> but when I pull those changes into another local repo, the tags do -not- 
> follow the objects:
> 
>     cd /spare/repo/misc-2.6
>     git checkout master
>     git pull ../linux-2.6
>     git fetch --tags ../linux-2.6    # still required to this day

I guess this is because /spare/repo/misc-2.6 does not have branches of 
/spare/repo/linux-2.6 configured as remote (tracking) branches.
-- 
Stefan Richter
-=====-==--- -==- ====-
http://arcgraph.de/sr/

Re: Updated Kernel Hacker's guide to git

[Jeff Garzik]

Jan Engelhardt wrote:
> On Dec 23 2007 06:13, Jeff Garzik wrote:
>> Another year, another update!  :)
>>
>> The kernel hacker's guide to git has received some updates:
>>
>> 	http://linux.yyz.us/git-howto.html
>>
> 
> It says
> 
> """Don't forget to download tags from time to time.
> 
> git pull only downloads sha1-indexed object data, and the requested
> remote head. This misses updates to the .git/refs/tags/ and
> .git/refs/heads/ directories. For tags, run git fetch --tags $URL."""
> 
> 
> But when I do git pull on a simple tracking tree (e.g. git-clone
> torvalds/linux-2.6.git; git pull;) it automatically grabs new tags.



Unfortunately tags are not copied in all cases.  To this day, I still 
have to 'git fetch --tags', generally when pulling from one local repo 
into another.  It's annoying that tags don't follow objects, when pulled.

	Jeff

Re: Updated Kernel Hacker's guide to git

[Christian Couder]

Hi,

Le lundi 30 juin 2008, Jeff Garzik a écrit :
> Jan Engelhardt wrote:
> > On Dec 23 2007 06:13, Jeff Garzik wrote:
> >> Another year, another update!  :)
> >>
> >> The kernel hacker's guide to git has received some updates:
> >>
> >> 	http://linux.yyz.us/git-howto.html

May I suggest adding some stuff about "git bisect", or at least links to 
other documentation about it, in this guide?

Especially, you may want to add an example about how to automate testing 
using "git bisect run" as you suggest other to do that:

http://www.ussg.iu.edu/hypermail/linux/kernel/0804.1/0633.html

Thanks in advance,
Christian.

Re: Updated Kernel Hacker's guide to git

[Francis Moreau]

Hi,

[ sorry for breaking up the thread but I'd like to fully
  understand that point and I just subscribed to git mail
  list... ]

Linus Torvalds wrote:
>
> On Wed, 20 Dec 2006, Jay Cliburn wrote:
>> $ git diff $(git merge-base master driver)..driver
>
> Be careful. This ONLY works if you don't have criss-cross merges etc, so
> you need to be somewhat careful about it. If you end up having a complex
> merge history between the origin branch and your development tree, things
> will stop working
>
> So it's actually worth understanding what the above does.
>
> Here's the picture to keep in mind: you started off with something like
> this:
>
> 	<- older			newer ->
>
> 	..--A---B---C---D
>
> where the top commit was D, and you started doing your own work off there.
> However, the tree you are tracking (doing "git fetch origin" or somethng)
> ALSO continues, so soon enough you'll have a history that looks like
>
> 	<- older			newer ->
>
> 	..--A---B---C---D---E---F---G---H <-"origin"
> 	                 \
> 	                  --X---Y---Z <- your "driver" branch"
>
> where your work is the "X-Y-Z" sequence.
>
> How, the reason you must NOT do
>
> 	git diff origin..driver
>
> or something like that, is that it will LITERALLY do a diff between those
> two heads. And while that is a perfectly normal diff, it's not what you
> want: it's the diff between the up-stream work and yours, and it will show
> that a lot of work has _not_ happened in your branch (all the E-F-G-H
> stuff), and then you've added some work (X-Y-Z).

I must really miss something but is a diff between origin and driver heads
achieved by:

	$ git diff driver origin

instead of:

	$ git diff origin..driver

?

>From the git-rev-list documentation I can read that:

	git-rev-list origin..driver == git-rev-list driver ^origin

I assume it's still true for git-diff. And the documentation says that
the above command "lists all the commits which are included in driver,
but not in origin".

So all commits included in driver are: (A-B-C-D-X-Y-Z)
all commits included in origin are: (A-B-C-D-E-F-G-H)

All the commits which are included in driver, but not in origin are:
(X-Y-Z), which is definitely not what you claimed.

I know that I'm wrong, so please shed some light in my stupid brain.

-- 
Francis

Re: Updated Kernel Hacker's guide to git

[Linus Torvalds]

On Thu, 21 Dec 2006, Francis Moreau wrote:
> 
> I must really miss something but is a diff between origin and driver heads
> achieved by:
> 
> 	$ git diff driver origin
> 
> instead of:
> 
> 	$ git diff origin..driver

No. 

	git diff origin driver

and

	git diff origin..driver

is exactly the same thing.

> From the git-rev-list documentation I can read that:
> 
> 	git-rev-list origin..driver == git-rev-list driver ^origin

Correct. However, "git diff" is very aware of things like "^origin", and 
understands that

	git diff driver ^origin

is the same thing as saying "I want what is in driver, but not in origin", 
so it needs to switch the arguments.

In short, for git diff (and ONLY) git diff, all of these are the same:

	git diff a..b
	git diff a b
	git diff b ^a

[ ADDITIONALLY git diff _also_ has a magic special case of

	git diff a b ^c

  which actually means the same as "git diff c..a" (and "b" is 
  totally ignored). That may sound strange, but it's because the 
  expression "a...b" means "b a --not $(git-merge-base a b)", and so what 
  you actually WANT is that if you do

	git diff a...b

  you should get "diff from merge-base to b", so when "a...b" expands to 
  "b a ^merge-base", then git understands that if it gets that stange 
  command line with THREE commits, and one of them is negated, you really 
  wanted the diff from the negated one to the first one ]

It basically all boils down to:

	"git diff" is special

exactly because unlike almost ALL other git commands, "git diff" does not 
work on a _list_ of commits, it only works on two end-points. That means 
that the "list operations" actually end up meaning something else for git 
diff than they do for "git log" and friends.

		Linus

Re: Updated Kernel Hacker's guide to git

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1685 bytes --]

On Thu, 21 Dec 2006 10:23:30 -0800 (PST), Linus Torvalds wrote:
> In short, for git diff (and ONLY) git diff, all of these are the same:
>
> 	git diff a..b
> 	git diff a b

I admit that I had had never passed a range of commits to git diff,
nor even given any thought to what it might do, but I definitely find
the above very surprising---and not necessarily very useful. Why is
anyone ever typing those two dots here if they have no effect on the
result?

> It basically all boils down to:
>
> 	"git diff" is special
>
> exactly because unlike almost ALL other git commands, "git diff" does not
> work on a _list_ of commits, it only works on two end-points. That means
> that the "list operations" actually end up meaning something else for git
> diff than they do for "git log" and friends.

Yes, "git diff" can only work on two end points. So a command like:

	git diff a b

is really easy to understand. And if the user wants to compare those
two points, why would the user ever provide them with any other
syntax?

In other words, what's the advantage of "git diff" accepting a special
syntax for a range ("a..b") and yet not actually doing anything
special with it?

In particular, the operation that would be interesting here is what
one can get with:

	git diff $(git merge-base a b) b

so why isn't _that_ the operation that is accessed with the syntax of:

	git diff a..b

Said another way, if "git log a..b" displays a range of commits, why
doesn't "git diff a..b" display the diff from the beginning of that
range to the end?

Of course, all the warnings you gave about what "git diff" would do
in the case of various criss-cross merge scenarios would still apply.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Updated Kernel Hacker's guide to git

[Linus Torvalds]

On Thu, 21 Dec 2006, Carl Worth wrote:
>
> On Thu, 21 Dec 2006 10:23:30 -0800 (PST), Linus Torvalds wrote:
> > In short, for git diff (and ONLY) git diff, all of these are the same:
> >
> > 	git diff a..b
> > 	git diff a b
> 
> I admit that I had had never passed a range of commits to git diff,
> nor even given any thought to what it might do, but I definitely find
> the above very surprising---and not necessarily very useful. Why is
> anyone ever typing those two dots here if they have no effect on the
> result?

I do it all the time, I never even use the old-fashioned syntax any more. 
It's much more concise and easy to read, and it has all the nice shortcuts 
(like empty meaning "HEAD", so you can do "git diff ..next" to see the 
diff from HEAD to another branch).

It's also useful exactly because of the semantics of things like "...".

In other words, sure, "git diff a b" works, but it just _looks_ more 
pleasing to use "a..b" and you mentally always pronounce the ".." as "to".

So "git diff a b" doesn't even look good to me any more, because it's 
literally missing that mental "to" that the ".." adds for me when I read 
it.

		Linus

Re: Updated Kernel Hacker's guide to git

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1965 bytes --]

On Thu, 21 Dec 2006 20:13:52 -0800 (PST), Linus Torvalds wrote:
> I do it all the time, I never even use the old-fashioned syntax any more.
> It's much more concise and easy to read, and it has all the nice shortcuts
> (like empty meaning "HEAD", so you can do "git diff ..next" to see the
> diff from HEAD to another branch).

I can understand the advantage of a shortcut like "git diff ..next",
but I still don't understand why it's the comparison of HEAD and next
that's really interesting here. Wouldn't comparing the merge-base to
next be more desirable? For example, if I'm considering whether to
merge in next or not, why should I care to see in the diff all the
irrelevant stuff that's happened on HEAD since next branched off?

But, really, I still don't understand exactly _what_ "diff a..b" even
means. Can you explain it to me?

Presumably the rev-parse magic is happening to the arguments. So does
the diff code just end up seeing the expanded equivalent of "b ^a" and
then just use the ^ to decide which tree to be on the left side or
something?

> It's also useful exactly because of the semantics of things like "...".

And now I'm really confused. If I'm not mistaken, rev-parse will turn
"a...b" into something like "a b ^$(merge-base a b)", right? So does
the diff code now end up seeing three different tree specifiers? What
does it do with that? And how is this useful? (As you said before,
diff is always going to end up acting on only two items, so I don't
see where there could be an interesting distinction from how you
obtain two items from "a..b" compared to "a...b".) But it might be
just that I'm really confused here.

> So "git diff a b" doesn't even look good to me any more, because it's
> literally missing that mental "to" that the ".." adds for me when I read
> it.

OK, that's fine. But can you comment on why you want the comparison
between the tips and not something based on a comparison from the
merge-base to a tip?

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Updated Kernel Hacker's guide to git

[Linus Torvalds]

On Fri, 22 Dec 2006, Carl Worth wrote:
> 
> I can understand the advantage of a shortcut like "git diff ..next",
> but I still don't understand why it's the comparison of HEAD and next
> that's really interesting here.

I can't understand why people complain about this.

YOU DON'T HAVE TO USE IT. 

Nobvody forces you. Really. And dammit, if I want to compare HEAD and 
next, I compare HEAD and next. You have absolutely no business saying that 
you don't understand why I'd want to do it. It's MY LIFE.

> But, really, I still don't understand exactly _what_ "diff a..b" even
> means. Can you explain it to me?

It means exactly the same as "diff a b".

It's that simple.

So now go away. Stop complaining.

		Linus

Re: Updated Kernel Hacker's guide to git

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Thu, 21 Dec 2006 20:13:52 -0800 (PST), Linus Torvalds wrote:
>> I do it all the time, I never even use the old-fashioned syntax any more.
>> It's much more concise and easy to read, and it has all the nice shortcuts
>> (like empty meaning "HEAD", so you can do "git diff ..next" to see the
>> diff from HEAD to another branch).
>
> I can understand the advantage of a shortcut like "git diff ..next",
> but I still don't understand why it's the comparison of HEAD and next
> that's really interesting here. Wouldn't comparing the merge-base to
> next be more desirable?

"git diff ...next" should work just as well, I think.

> But, really, I still don't understand exactly _what_ "diff a..b" even
> means. Can you explain it to me?

diff between two points.

> Presumably the rev-parse magic is happening to the arguments. So does
> the diff code just end up seeing the expanded equivalent of "b ^a" and
> then just use the ^ to decide which tree to be on the left side or
> something?

Exactly; diff just reuses the non-magic part of revision
parameter parsing without using the ancestry traversal
machinery (which is the magic part).

>> It's also useful exactly because of the semantics of things like "...".
>
> And now I'm really confused. If I'm not mistaken, rev-parse will turn
> "a...b" into something like "a b ^$(merge-base a b)", right? So does
> the diff code now end up seeing three different tree specifiers? What
> does it do with that?

It knows that rev-parse makes it "b a ^base", and it knows what
the user meant is "base..b".

That's all because we teach them to spell "a...b" when they want
"base..b".  Similarly, because we allow them to spell "a..b"
when they mean "between two points, a and b", it handles "b ^a"
as the equivalent to giving two trees separately, as "a b".

> And how is this useful? (As you said before,
> diff is always going to end up acting on only two items, so I don't
> see where there could be an interesting distinction from how you
> obtain two items from "a..b" compared to "a...b".) But it might be
> just that I'm really confused here.

I do not think you are seriously saying that comparing A and
B in this picture is meaningless:

      o---o---B
     /
 ---M---o---A

Yes, it is often useful to compare M and B, but that "often" is
limited to the phase of the workflow where you are at A and are
contemplating of merging B.  But merging two forked branches is
not the only thing you do.

Comparing two revisions regardless of how they are topologically
related is useful as often.  It is only that it may not as
useful while you are trying to merge B into A.

So there are two ways to let you do both, and they need to be
specified differently (.. vs ...)  because you need to tell it
to do which one.

Re: Updated Kernel Hacker's guide to git

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2308 bytes --]

On Fri, 22 Dec 2006 14:45:18 -0800, Junio C Hamano wrote:
> Exactly; diff just reuses the non-magic part of revision
> parameter parsing without using the ancestry traversal
> machinery (which is the magic part).

Thanks, that helps.

> It knows that rev-parse makes it "b a ^base", and it knows what
> the user meant is "base..b".

Ahah! So the "a...b" syntax is how to get at what:

	git diff $(git merge-base a b) b

would give. Thanks for explaining, since that was not at all obvious.

> That's all because we teach them to spell "a...b" when they want
> "base..b".  Similarly, because we allow them to spell "a..b"
> when they mean "between two points, a and b", it handles "b ^a"
> as the equivalent to giving two trees separately, as "a b".

Where is that teaching happening exactly? Both the "a..b" and "a...b"
forms seem to be entirely missing from the documentation of git
diff. :-)

> I do not think you are seriously saying that comparing A and
> B in this picture is meaningless:
>
>       o---o---B
>      /
>  ---M---o---A

No, I'm certainly not saying that that that comparison is meaningless.

All I was trying to say is that comparing M to B would be meaningful
too, and I hoped that git would provide good syntax for both. If I'm
understanding things correctly now, what exists is:

  git diff A B
  git diff A..B

	Compare A to B

  git diff A...B

	Compare M to B

So, at the beginning of this thread I wasn't aware that git provided
any short syntax for the "M to B" comparison, (the thread started with
suggestions for adding "git diff $(git merge-base A B) B" to the
hackers guide).

Now, I'm happy to know that git does provide a short syntax for that
useful operation.

My only comment now is that the distinction between ".." and "..." in
git-diff is quite surprising. In fact, in one sense it's exactly
opposite from the distinction of ".." and "..." as used in git log.

For example, given the above graph, "git diff A..B" shows changes due
to all 5 of commits on both branches while "git log -p A..B" shows
only the changes of the 3 commits from M to B.

Meanwhile, "git diff A...B" shows changes due to the 3 commits from M
to B while "git log -p A...B" shows the changes from all 5 of the
commits on both branches.

That's really surprising behavior (to me at least).

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Updated Kernel Hacker's guide to git

[Jakub Narebski]

[Cc: Carl Worth <cworth@cworth.org>, Linus Torvalds <torvalds@osdl.org>
 git@vger.kernel.org]

Carl Worth wrote:

> On Thu, 21 Dec 2006 20:13:52 -0800 (PST), Linus Torvalds wrote:
>> I do it all the time, I never even use the old-fashioned syntax any more.
>> It's much more concise and easy to read, and it has all the nice shortcuts
>> (like empty meaning "HEAD", so you can do "git diff ..next" to see the
>> diff from HEAD to another branch).
> 
> I can understand the advantage of a shortcut like "git diff ..next",
> but I still don't understand why it's the comparison of HEAD and next
> that's really interesting here. Wouldn't comparing the merge-base to
> next be more desirable? For example, if I'm considering whether to
> merge in next or not, why should I care to see in the diff all the
> irrelevant stuff that's happened on HEAD since next branched off?
> 
> But, really, I still don't understand exactly _what_ "diff a..b" even
> means. Can you explain it to me?

For me, it's just a bit of syntactic sugar (I always have in mind that
git-log and friends outputs commit list and use revisions range, while
git-diff and friends needs two (or less) revisions) allowing to
copy'n'paste arguments from "git log a..b" to "git diff a..b"
 
> Presumably the rev-parse magic is happening to the arguments. So does
> the diff code just end up seeing the expanded equivalent of "b ^a" and
> then just use the ^ to decide which tree to be on the left side or
> something?

And that is just implementation. I don't think anyone uses "git diff b ^a".

>> It's also useful exactly because of the semantics of things like "...".
> 
> And now I'm really confused. If I'm not mistaken, rev-parse will turn
> "a...b" into something like "a b ^$(merge-base a b)", right? So does
> the diff code now end up seeing three different tree specifiers? What
> does it do with that? And how is this useful? (As you said before,
> diff is always going to end up acting on only two items, so I don't
> see where there could be an interesting distinction from how you
> obtain two items from "a..b" compared to "a...b".) But it might be
> just that I'm really confused here.

I would have thought that it would be combined diff of a and b against
it's merge base... but it is not.

"git diff a...b" is turned into "git diff a b ^$(git merge-base a b)",
and by a bit of magic (and by a convention) it is turned into
"git diff ^$(merge-base a b) a" (and a...b ceases to be _symmetric_
for git-diff).

I'd like for "git diff --cc a...b" to do 'the right thing' and show
git diff --cc for pretended merge (I'm not sure if with or without
resolving trivial conflicts).

>> So "git diff a b" doesn't even look good to me any more, because it's
>> literally missing that mental "to" that the ".." adds for me when I read
>> it.
> 
> OK, that's fine. But can you comment on why you want the comparison
> between the tips and not something based on a comparison from the
> merge-base to a tip?

a..b does not imply merge-base, a...b does.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Updated Kernel Hacker's guide to git

[Francis Moreau]

Linus Torvalds wrote:
>
> In short, for git diff (and ONLY) git diff, all of these are the same:
>
> 	git diff a..b
> 	git diff a b
> 	git diff b ^a
>

I think this part is really confusing. For a new comer, saying that:

	git diff a b == git diff a..b

is really not intuitive. Maybe just because adding a new symbol ".."
in git diff command line means (for me) that we're doing a special
diff. I would never thought by my own that ".." means a simple "to".

> [ ADDITIONALLY git diff _also_ has a magic special case of
>
> 	git diff a b ^c
>
>   which actually means the same as "git diff c..a" (and "b" is
>   totally ignored). That may sound strange, but it's because the
>   expression "a...b" means "b a --not $(git-merge-base a b)", and so what
>   you actually WANT is that if you do
>
> 	git diff a...b
>
>   you should get "diff from merge-base to b", so when "a...b" expands to
>   "b a ^merge-base", then git understands that if it gets that stange
>   command line with THREE commits, and one of them is negated, you really
>   wanted the diff from the negated one to the first one ]
>
> It basically all boils down to:
>
> 	"git diff" is special
>

but this very special part of git diff is also not documented at all
when reading the manual of git-diff... Maybe it can be reached by
others manuals ?

> exactly because unlike almost ALL other git commands, "git diff" does not
> work on a _list_ of commits, it only works on two end-points. That means
> that the "list operations" actually end up meaning something else for git
> diff than they do for "git log" and friends.
>

I think I got your point now: git-diff only works on two end-points.


Why not making it less special as follow:

	git diff a b
	git diff b ^a

These two diff commands are the same. They do a diff between a and b
end-points (maybe commits is better there since we don't add one more
keyword). It's similar to diff command. For me it's quite intuitive.

	git diff a..b

Ok now the command syntax is more special (maybe simply because
traditional diff() does not have a similar syntax, it's really
specific to git). "git log" and friends have a similar syntax and they
do work on a list of commits. For consistency sake, make this commad
works on commit list too. Therefore this command would end up doing
exactly the same thing like "git diff a...b"

	git diff a...b

No more need of this special syntax.


What do you think ?

thanks
-- 
Francis

Re: Updated Kernel Hacker's guide to git

[Junio C Hamano]

"Francis Moreau" <francis.moro@gmail.com> writes:

> I think this part is really confusing. For a new comer, saying that:
>
> 	git diff a b == git diff a..b
>
> is really not intuitive. Maybe just because adding a new symbol ".."
> in git diff command line means (for me) that we're doing a special
> diff. I would never thought by my own that ".." means a simple "to".

We did not originally have "A B"; you were supposed to always
say "A..B".  But all other SCM had "A B" notation, so we added
support for both because doing so was trivial and there is no
risk of confusion (because diff is about two points while log is
about a set).  These two notations are interchangeable for
"diff".  If it confuses you, you can stick to the "git diff A B"
notation.  Of if you are like Linus, stick to "A..B" notation.
Either way, you can pretend that the other notation does not
even exist and be happy ;-).

Yes, users often wondered why "git diff" accepts "A B", "git
log" wants "A..B" and "git log A B" is a disaster.  But the root
cause of the confusion was not about notation but about the
conceptual difference (two points vs a set).

I do not think changing the meaning of "diff A..B" to what "diff
A...B" means is a good thing.  The notation "..." even _looks_
like a magic, and in diff context, what it does _is_ magic (it
is magic in log context, too).  You are giving two points, but
what actually is used as the two points for diff are different
from what you gave; in that sense, it is a very good notation.
Changing it would confuse and inconvenience people who already
understood and got used to the difference between "diff" and
"log": diff takes two points, so given usual A..B notation it
uses A and B, while log is about a set and means 'the ones
reachable from B, excluding the ones reachable from A'; "A...B"
is magic and does a magical thing in both "diff" and "log",
taking the merge bases between A and B into account.

Re: Updated Kernel Hacker's guide to git

[Francis Moreau]

On 12/22/06, Junio C Hamano <junkio@cox.net> wrote:
> "Francis Moreau" <francis.moro@gmail.com> writes:
>
> > I think this part is really confusing. For a new comer, saying that:
> >
> >       git diff a b == git diff a..b
> >
> > is really not intuitive. Maybe just because adding a new symbol ".."
> > in git diff command line means (for me) that we're doing a special
> > diff. I would never thought by my own that ".." means a simple "to".
>
> We did not originally have "A B"; you were supposed to always
> say "A..B".  But all other SCM had "A B" notation, so we added
> support for both because doing so was trivial and there is no
> risk of confusion (because diff is about two points while log is
> about a set).  These two notations are interchangeable for
> "diff".  If it confuses you, you can stick to the "git diff A B"
> notation.  Of if you are like Linus, stick to "A..B" notation.
> Either way, you can pretend that the other notation does not
> even exist and be happy ;-).
>

no, no, I think you miss my point here. What is confusing, and it
seems I'm not the only one to find it confusing,  is the fact that
"git diff A B == git diff A..B", not the "A..B" notation per se.

git diff A B, is really intuitive and easy to understand because we
all use to using the diff "A B" notation and it always has worked with
2 endpoints. So I would bet that all newbies who use for the first
time the git diff command will use "A B" notation, not "A..B" one.

> Yes, users often wondered why "git diff" accepts "A B", "git
> log" wants "A..B" and "git log A B" is a disaster.  But the root
> cause of the confusion was not about notation but about the
> conceptual difference (two points vs a set).
>
> I do not think changing the meaning of "diff A..B" to what "diff
> A...B" means is a good thing.  The notation "..." even _looks_
> like a magic, and in diff context, what it does _is_ magic (it
> is magic in log context, too).  You are giving two points, but

But ".." is magic too ! I would really expect something magic to
happen when using the "A..B" notation because I'm a new comer in git
and I never used the "A..B" notation before.

And since I already used this notation when using git log command, I
would expect "git diff A..B" to give the current result given by "git
diff A...B".

But yes, now I have understand that git diff works with end points
unlike git log, I can stick with two notations:

        git diff A B
        git diff A...B (3 dots)

and I'm happy ;)

thanks
-- 
Francis