From: Junio C Hamano Date: Thu, 23 Jun 2011 15:33:05 +0000 (-0700) Subject: git-remote.txt: avoid sounding as if loose refs are the only ones in the world X-Git-Tag: v1.7.6.1~41^2~5 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/0aceb220972413e73157cb46a8a52e0f6034d54c 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 --- diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 1e3945f0b0..5a8c5061f3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -60,11 +60,11 @@ the remote repository. + With `-t ` option, instead of the default glob refspec for the remote to track all branches under -`$GIT_DIR/refs/remotes//`, a refspec to track only `` +the `refs/remotes//` namespace, a refspec to track only `` is created. You can give more than one `-t ` to track multiple branches without grabbing all branches. + -With `-m ` option, `$GIT_DIR/refs/remotes//HEAD` is set +With `-m ` option, a symbolic-ref `refs/remotes//HEAD` is set up to point at remote's `` branch. See also the set-head command. + When a fetch mirror is created with `\--mirror=fetch`, the refs will not @@ -92,24 +92,25 @@ configuration settings for the remote are removed. 'set-head':: -Sets or deletes the default branch (`$GIT_DIR/refs/remotes//HEAD`) for +Sets or deletes the default branch (i.e. the target of the +symbolic-ref `refs/remotes//HEAD`) for the named remote. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch. For example, if the default branch for `origin` is set to `master`, then `origin` may be specified wherever you would normally specify `origin/master`. + -With `-d`, `$GIT_DIR/refs/remotes//HEAD` is deleted. +With `-d`, the symbolic ref `refs/remotes//HEAD` is deleted. + -With `-a`, the remote is queried to determine its `HEAD`, then -`$GIT_DIR/refs/remotes//HEAD` is set to the same branch. e.g., if the remote +With `-a`, the remote is queried to determine its `HEAD`, then the +symbolic-ref `refs/remotes//HEAD` is set to the same branch. e.g., if the remote `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set -`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will +the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `` to set `$GIT_DIR/refs/remotes//HEAD` explicitly. e.g., "git -remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to +Use `` to set the symbolic-ref `refs/remotes//HEAD` explicitly. e.g., "git +remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. +