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" <bfields@citi.umich.edu>
J. Bruce Fields committed
Jan 21, 2007 at 22:31 UTC
f60b964249fb38fea7906559875c600665a2d991
1 file changed
+19
-27
Documentation/user-manual.txt
+19
-27
@@ -506,41 +506,33 @@ Note that the name "origin" is just the name that git uses by default
506
to refer to the repository that you cloned from.
507
508
[[how-git-stores-references]]
509
-How git stores references
510
--------------------------
509
+Naming branches, tags, and other references
510
+-------------------------------------------
511
512
Branches, remote-tracking branches, and tags are all references to
513
-commits. Git stores these references in the ".git" directory. Most
514
-of them are stored in .git/refs/:
515
-
516
- - branches are stored in .git/refs/heads
517
- - tags are stored in .git/refs/tags
518
- - remote-tracking branches for "origin" are stored in
519
- .git/refs/remotes/origin/
513
+commits. All references are named with a slash-separated path name
514
+starting with "refs"; the names we've been using so far are actually
515
+shorthand:
516
521
-If you look at one of these files you will see that they usually
522
-contain just the SHA1 id of a commit:
517
+ - The branch "test" is short for "refs/heads/test".
518
+ - The tag "v2.6.18" is short for "refs/tags/v2.6.18".
519
+ - "origin/master" is short for "refs/remotes/origin/master".
520
524
-------------------------------------------------
525
-$ ls .git/refs/heads/
526
-master
527
-$ cat .git/refs/heads/master
528
-c0f982dcf188d55db9d932a39d4ea7becaa55fed
529
-------------------------------------------------
521
+The full name is occasionally useful if, for example, there ever
522
+exists a tag and a branch with the same name.
523
531
-You can refer to a reference by its path relative to the .git
532
-directory. However, we've seen above that git will also accept
533
-shorter names; for example, "master" is an acceptable shortcut for
534
-"refs/heads/master", and "origin/master" is a shortcut for
535
-"refs/remotes/origin/master".
524
+As another useful shortcut, if the repository "origin" posesses only
525
+a single branch, you can refer to that branch as just "origin".
526
537
-As another useful shortcut, you can also refer to the "HEAD" of
538
-"origin" (or any other remote), using just the name of the remote.
527
+More generally, if you have defined a remote repository named
528
+"example", you can refer to the branch in that repository as
529
+"example". And for a repository with multiple branches, this will
530
+refer to the branch designated as the "HEAD" branch.
531
532
For the complete list of paths which git checks for references, and
541
-how it decides which to choose when there are multiple references
542
-with the same name, see the "SPECIFYING REVISIONS" section of
543
-gitlink:git-rev-parse[1].
533
+the order it uses to decide which to choose when there are multiple
534
+references with the same shorthand name, see the "SPECIFYING
535
+REVISIONS" section of gitlink:git-rev-parse[1].
536
537
[[Updating-a-repository-with-git-fetch]]
538
Updating a repository with git fetch