From eb637e138289dc5b96bea5b192cbaff93623d1dc Mon Sep 17 00:00:00 2001 From: Namhyung Kim Date: Thu, 23 Jun 2011 17:12:04 +0900 Subject: git-remote.txt: fix wrong remote refspec $GIT_DIR/remotes// should be $GIT_DIR/refs/remotes//. Signed-off-by: Namhyung Kim Signed-off-by: Junio C Hamano diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 528f34a..1e3945f 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/remotes//`, a refspec to track only `` +`$GIT_DIR/refs/remotes//`, 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/remotes//HEAD` is set +With `-m ` option, `$GIT_DIR/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,23 +92,23 @@ configuration settings for the remote are removed. 'set-head':: -Sets or deletes the default branch (`$GIT_DIR/remotes//HEAD`) for +Sets or deletes the default branch (`$GIT_DIR/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/remotes//HEAD` is deleted. +With `-d`, `$GIT_DIR/refs/remotes//HEAD` is deleted. + With `-a`, the remote is queried to determine its `HEAD`, then -`$GIT_DIR/remotes//HEAD` is set to the same branch. e.g., if the remote +`$GIT_DIR/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 only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `` to set `$GIT_DIR/remotes//HEAD` explicitly. e.g., "git +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 `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. -- cgit v0.10.2-6-g49f6 From 0aceb220972413e73157cb46a8a52e0f6034d54c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 08:33:05 -0700 Subject: 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 1e3945f..5a8c506 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. + -- cgit v0.10.2-6-g49f6 From a0a7e9e511faa86663148557d0f5b0597767d25a Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 09:31:19 -0700 Subject: check-ref-format doc: de-emphasize the implementation detail of a ref It is an unimportant implementation detail that branches and tags are stored somewhere under $GIT_DIR/refs directory. What is more important is that branches live in refs/heads and tags live in refs/tags hierarchy in the ref namespace. Signed-off-by: Junio C Hamano diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 205d83d..c9fdf84 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -18,9 +18,12 @@ Checks if a given 'refname' is acceptable, and exits with a non-zero status if it is not. A reference is used in git to specify branches and tags. A -branch head is stored under the `$GIT_DIR/refs/heads` directory, and -a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs -are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file). +branch head is stored in the `refs/heads` hierarchy, while +a tag is stored in the `refs/tags` hierarchy of the ref namespace +(typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags` +directories or, as entries in file `$GIT_DIR/packed-refs` +if refs are packed by `git gc`). + git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) -- cgit v0.10.2-6-g49f6 From 0abcfbff4ddaf08e5aa2524f28a7035095b6d0c9 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 09:35:10 -0700 Subject: git.txt: de-emphasize the implementation detail of a ref It is an unimportant implementation detail that branches and tags are stored somewhere under $GIT_DIR/refs directory, or the name of the commit that will become the parent of the next commit is stored in $GIT_DIR/HEAD. What is more important is that branches live in refs/heads and tags live in refs/tags hierarchy in the ref namespace, and HEAD means the tip of the current branch. Signed-off-by: Junio C Hamano diff --git a/Documentation/git.txt b/Documentation/git.txt index 8c0bfdf..7fc6b88 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -510,16 +510,15 @@ Any git command accepting any can also use the following symbolic notation: HEAD:: - indicates the head of the current branch (i.e. the - contents of `$GIT_DIR/HEAD`). + indicates the head of the current branch. :: a valid tag 'name' - (i.e. the contents of `$GIT_DIR/refs/tags/`). + (i.e. a `refs/tags/` reference). :: a valid head 'name' - (i.e. the contents of `$GIT_DIR/refs/heads/`). + (i.e. a `refs/heads/` reference). For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. -- cgit v0.10.2-6-g49f6 From 487b04411d625ff912543e4313a3343db62429e4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 09:38:48 -0700 Subject: glossary: update description of "tag" It is an unimportant implementation detail that ref namespaces are implemented as subdirectories of $GIT_DIR/refs. What is more important is that tags are in refs/tags hierarchy in the ref namespace. Also note that a tag can point at an object of arbitrary type, not limited to commit. Signed-off-by: Junio C Hamano diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 33716a3..878de21 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -427,14 +427,14 @@ including Documentation/chapter_1/figure_1.jpg. command. [[def_tag]]tag:: - A <> pointing to a <> or - <>. In contrast to a <>, - a tag is not changed by a <>. Tags (not - <>) are stored in `$GIT_DIR/refs/tags/`. A - git tag has nothing to do with a Lisp tag (which would be - called an <> in git's context). A - tag is most typically used to mark a particular point in the - commit ancestry <>. + A <> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <> or a <>). + In contrast to a <>, a tag is not updated by + the `commit` command. A git tag has nothing to do with a Lisp + tag (which would be called an <> + in git's context). A tag is most typically used to mark a particular + point in the commit ancestry <>. [[def_tag_object]]tag object:: An <> containing a <> pointing to -- cgit v0.10.2-6-g49f6 From deaef1e94734a61407c73637e0e9718f914c3a62 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 09:47:28 -0700 Subject: glossary: update description of head and ref Reword them to avoid sounding as if loose refs are the only ones in the world. Signed-off-by: Junio C Hamano diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 878de21..f430068 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -161,8 +161,8 @@ to point at the new commit. [[def_head]]head:: A <> to the <> at the tip of a - <>. Heads are stored in - `$GIT_DIR/refs/heads/`, except when using packed refs. (See + <>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: @@ -350,8 +350,9 @@ including Documentation/chapter_1/figure_1.jpg. [[def_ref]]ref:: A 40-byte hex representation of a <> or a name that - denotes a particular <>. These may be stored in - `$GIT_DIR/refs/`. + denotes a particular <>. They may be stored in + a file under `$GIT_DIR/refs/` directory, or + in the `$GIT_DIR/packed-refs` file. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, -- cgit v0.10.2-6-g49f6 From 67393c5dc99eb61e76d2ea4df3dae49e8e93828d Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 23 Jun 2011 09:48:49 -0700 Subject: glossary: clarify description of HEAD HEAD on a branch does reference a commit via the branch ref it refers to. The main difference of a detached HEAD is that it _directly_ refers to a commit. Clarify this. Signed-off-by: Junio C Hamano diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f430068..f4fd5b0 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -170,8 +170,8 @@ to point at the new commit. working tree>> is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the <> in your repository, except when using a - <>, in which case it may - reference an arbitrary commit. + <>, in which case it directly + references an arbitrary commit. [[def_head_ref]]head ref:: A synonym for <>. -- cgit v0.10.2-6-g49f6