From: J. Bruce Fields Date: Mon, 22 Jan 2007 03:31:07 +0000 (-0500) Subject: user-manual: update references discussion X-Git-Tag: v1.5.0-rc3~3^2~17 X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=f60b964249fb38fea7906559875c600665a2d991;p=git.git user-manual: update references discussion Since references may be packed, it's no longer as helpful to introduce references as paths relative to .git. Signed-off-by: "J. Bruce Fields" --- diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 267bbd736..6c858aadd 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -506,41 +506,33 @@ Note that the name "origin" is just the name that git uses by default to refer to the repository that you cloned from. [[how-git-stores-references]] -How git stores references -------------------------- +Naming branches, tags, and other references +------------------------------------------- Branches, remote-tracking branches, and tags are all references to -commits. Git stores these references in the ".git" directory. Most -of them are stored in .git/refs/: - - - branches are stored in .git/refs/heads - - tags are stored in .git/refs/tags - - remote-tracking branches for "origin" are stored in - .git/refs/remotes/origin/ +commits. All references are named with a slash-separated path name +starting with "refs"; the names we've been using so far are actually +shorthand: -If you look at one of these files you will see that they usually -contain just the SHA1 id of a commit: + - The branch "test" is short for "refs/heads/test". + - The tag "v2.6.18" is short for "refs/tags/v2.6.18". + - "origin/master" is short for "refs/remotes/origin/master". ------------------------------------------------- -$ ls .git/refs/heads/ -master -$ cat .git/refs/heads/master -c0f982dcf188d55db9d932a39d4ea7becaa55fed ------------------------------------------------- +The full name is occasionally useful if, for example, there ever +exists a tag and a branch with the same name. -You can refer to a reference by its path relative to the .git -directory. However, we've seen above that git will also accept -shorter names; for example, "master" is an acceptable shortcut for -"refs/heads/master", and "origin/master" is a shortcut for -"refs/remotes/origin/master". +As another useful shortcut, if the repository "origin" posesses only +a single branch, you can refer to that branch as just "origin". -As another useful shortcut, you can also refer to the "HEAD" of -"origin" (or any other remote), using just the name of the remote. +More generally, if you have defined a remote repository named +"example", you can refer to the branch in that repository as +"example". And for a repository with multiple branches, this will +refer to the branch designated as the "HEAD" branch. For the complete list of paths which git checks for references, and -how it decides which to choose when there are multiple references -with the same name, see the "SPECIFYING REVISIONS" section of -gitlink:git-rev-parse[1]. +the order it uses to decide which to choose when there are multiple +references with the same shorthand name, see the "SPECIFYING +REVISIONS" section of gitlink:git-rev-parse[1]. [[Updating-a-repository-with-git-fetch]] Updating a repository with git fetch