Re: Process to push changes to include/linux/types.h

[Linus Torvalds]

On Thu, Oct 14, 2010 at 2:50 PM, Jan Engelhardt <jengelh@xxxxxxxxxx> wrote:
>
>>> (See v2.6.24-6165-gc82a5cb)
>>
>>hm, what does that mean.
>
> Eh, it's a git commit identifier. When people throw around with these
> (or their longer, 40-char variants), it is suggested to use `git log
> -1 -p v2.6.24-6165-gc82a5cb` to see the details.

[ I'm sure you know this, but just for any innocent non-git
by-standers out there ]

Well, technically it's more than just a git ID. It actually has some
descriptive value, and it's generated by "git descibe".

In something like the above, the only part git cares about in this
case is the (shortened) SHA1 hash, ie the "c82a5cb" part. Everything
else is just a mostly human-readable description, which boils down to
"based on v2.6.24, there's 6165 additional commits, and git commit
c82a5cb is where you end up". So the output is designed to (a) give
some helpful information even for intermediate places that aren't
exact tagged releases and (b) also work with other SCM's (that "-g"
part there is for "git" - but scripts/setlocalversion is able to give
somewhat reasonable output for hg and svn too.

Extended background for non-git people: git _internally_ only uses the
160-bit SHA1 (which in its full ASCII form is 40 hex characters). But
because that is so human-unfriendly, there are various human-readable
ways to express it:

 - Just a shortened unique version, usually 7-12 hex characters. 12
hex characters is already unique in practice for pretty much any
reasonable project, and is much easier to write.

   I tend to use the 12-character short version in commit messages,
for example. The full 40-character SHA1 makes it hard to do any sane
line breaks with in the commit message.

 - named tags or branches ("v2.6.36-rc7", or "master" etc)

 - The <random human-readable noise> + "-g" + <shortened SHA1> thing
described above (output by "git describe", and on input git ignores
the human-readable part), where the human-readable part tries to give
a release as a base for it.

 - a "git revision expression", where you can mix and match SHA1's or
named tags/branches, and their parenthood relationsips.

So that "v2.6.24-6165-gc82a5cb" could be expressed as

 - c82a5cb8b2b2ce15f1fb8add6772921b72da5943 (full SHA1)

 - c82a5cb8b2b2 (abbreviated to 12 hex chars)

 - v2.6.25-rc1~1089^2~98

where that last one is saying "you can reach it from v2.6.25-rc1 by
walking 1089 parents down, then taking the second parent in that
merge, and then walking 98 parents down again".

It's worth noting that the "v2.6.24-6165" - while human-readable and
thus useful - is technically meaningless. Since development isn't a
straight line, "6165 commits after 2.6.24" is really not a
well-defined point. It tells you _something_ - namely "not really very
close to plain 2.6.24" - but there may well be many places in the
history that are 6165 commits away from 2.6.24.

Which is why git really just ignores that human-readable part on input.

In contrast, the "v2.6.25-rc1~1089^2~98" expression is actually
well-defined. There is no ambiguity there, but it's also obviously not
really all that human-readable.

                              Linus
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/