linux@horizon.com writes:

quoted text
> I know it took me a while to get used to playing with branches, and I
> still get nervous when doing something creative.  So I've been trying
> to get more comfortable, and wrote the following to document what I've
> learned.
>
> It's a first draft - I just finished writing it, so there are probably
> some glaring errors - but I thought it might be of interest anyway.

This is a greatest write-up I've seen for the past several
months.  I find it very balanced to point out the quirks people
would find difficult and explain why things are so by including
historical notes in appropriate places when needed.  Definitely
Documentation/ material when copyediting is done.

I have finished only the first half because it's not my git day
today, but so far...

quoted text
> * Naming revisions
>...
> Second, you can refer to a head or tag name.  Git looks in the
> following places, in order, for a head:
> 	1) .git
> 	2) .git/refs
> 	3) .git/refs/heads
> 	4) .git/refs/tags

You might want to check this with the array in sha1_name.c::get_sha1_basic().
I think tags comes earlier than heads.

quoted text
> 2) Revert changes to a small number of files.
>
> 	git checkout [<revision>] [--] <paths>
>    will copy the version of the <paths> from the index to the working
>    directory.  If a <revision> is given, the index for those paths will
>    be updated from the given revision before copying from the index to
>    the working tree.
>
>    Unlike the version with no <paths> specified, this does NOT update
>    HEAD, even if <paths> is ".".

It's great that you talk correctly about the latest feature-fix
that is queued for maint but not yet pushed out.

quoted text
> 2) By path name.  This is a feature which appears to be unique to git.
>    If you give git-rev-list (or git-log, or gitk, or qgit) a list of
>    pathname prefixes, it will list only commits which touch those
>    paths. So "git log drivers/scsi include/scsi" will list only
>    commits which alters a file whose name begins with drivers/scsi
>    or include/scsi.
>
>    (If there's any possible ambiguity between a path name and a commit
>    name, git-rev-list will refuse to proceed.  You can resolve it by
>    including "--" on the command line.  Everything before that is a
>    commit name; everything after is a path.)
>
>    This filter is in addition to the ancestry filter.  It's also rather
>    clever about omitting unnecessary detail.  In particular, if there's
>    a side branch which does touch drivers/scsi, then the entire branch,
>    and the merge at the end, will be removed from the log.

"If there's a side branch which does NOT touch the paths..." I think.

quoted text
> * Alternate branch naming
>
> The original git scheme mixes tracking branches with all the other heads.
> This requires that you remember which branches are tracking branches and
> which aren't.  Hopefully, you remember what all your branches are for,
> but if you track a lot of remote repositories, you might not remember
> what every remote branch is for and what you called it locally.

I think you wanted to mention .git/refs/remotes hierarchy and
separate-remote here, but haven't elaborated yet...

quoted text
> * Remote tags
>
> TODO: Figure out how remote tags work, under what circumstances
> they are fetched, and what git does if there are conflicts.

refs/tags namespace is not policed at all by git and is treated
as a global namespace, controlled mostly by social convention
that your "upstream" (or central distribution point) supplies
tags for people who use it to synchronize to share.  Also, since
there is no guarantee that tags point at commits (v2.6.11-tree
tag is a pointer to a tree object, for example), there is no
farst-forward check performed for them.

The rule we use to autofollow tags currently is:

When you use shorthand fetch (or pull), we find tags that do not
exist locally, and if the object they point at are already found
in the repository then we fetch them automatically.  So for
example, if you are only tracking my 'maint' and not 'master'
nor 'next', and if you have tags up to v1.4.3.2, your "git fetch
origin" would update your copy of 'maint' and bring the commits
reachable from the tip of my 'maint'.  After that it notices
that v1.4.3.3, v1.4.3.4, v1.4.3.5 tags are in my repository but
missing from yours. It also notices that now you have
v1.4.3.3^{}, v1.4.3.4^{} and v1.4.3.5^{} in your repository, so
it issues another round of "git fetch" internally to fetch these
three tags.  At the same time it would also notice that I have
v1.4.4 tag that you do not have, but v1.4.4^0 commit is not
something you would get by fetching 'maint', so it would not
fetch it automatically.

-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html