git-remote.txt: avoid sounding as if loose refs are the only ones in the world
It was correct to say "The file $GIT_DIR/refs/heads/master stores the commit object name at the tip of the master branch" in the older days, but not anymore, as refs can be packed into $GIT_DIR/packed-refs file. Update the document to talk in terms of a more abstract concept "ref" and "symbolic ref" where we are not describing the underlying implementation detail. This on purpose leaves two instances of $GIT_DIR/ in the git-remote documentation; they do talk about $GIT_DIR/remotes/ and $GIT_DIR/branches/ file hierarchy that used to be the place to store configuration around remotes before the configuration mechanism took them over. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jun 23, 2011 at 08:33 UTC
0aceb220972413e73157cb46a8a52e0f6034d54c
1 file changed
+10
-9
Documentation/git-remote.txt
+10
-9
@@ -60,11 +60,11 @@ the remote repository.
60
+
61
With `-t <branch>` option, instead of the default glob
62
refspec for the remote to track all branches under
63
-`$GIT_DIR/refs/remotes/<name>/`, a refspec to track only `<branch>`
63
+the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>`
64
is created. You can give more than one `-t <branch>` to track
65
multiple branches without grabbing all branches.
66
+
67
-With `-m <master>` option, `$GIT_DIR/refs/remotes/<name>/HEAD` is set
67
+With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set
68
up to point at remote's `<master>` branch. See also the set-head command.
69
+
70
When a fetch mirror is created with `\--mirror=fetch`, the refs will not
@@ -92,24 +92,25 @@ configuration settings for the remote are removed.
92
93
'set-head'::
94
95
-Sets or deletes the default branch (`$GIT_DIR/refs/remotes/<name>/HEAD`) for
95
+Sets or deletes the default branch (i.e. the target of the
96
+symbolic-ref `refs/remotes/<name>/HEAD`) for
97
the named remote. Having a default branch for a remote is not required,
98
but allows the name of the remote to be specified in lieu of a specific
99
branch. For example, if the default branch for `origin` is set to
100
`master`, then `origin` may be specified wherever you would normally
101
specify `origin/master`.
102
+
102
-With `-d`, `$GIT_DIR/refs/remotes/<name>/HEAD` is deleted.
103
+With `-d`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted.
104
+
104
-With `-a`, the remote is queried to determine its `HEAD`, then
105
-`$GIT_DIR/refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote
105
+With `-a`, the remote is queried to determine its `HEAD`, then the
106
+symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote
107
`HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set
107
-`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will
108
+the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will
109
only work if `refs/remotes/origin/next` already exists; if not it must be
110
fetched first.
111
+
111
-Use `<branch>` to set `$GIT_DIR/refs/remotes/<name>/HEAD` explicitly. e.g., "git
112
-remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to
112
+Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git
113
+remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to
114
`refs/remotes/origin/master`. This will only work if
115
`refs/remotes/origin/master` already exists; if not it must be fetched first.
116
+