From 604e0cb5cbd2ea2e37273e13f99b6572cd82b4c1 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 12 Oct 2009 00:28:23 -0500 Subject: Documentation: describe check-ref-format --branch Unless one already knew, it was not obvious what sort of shorthand "git check-ref-format --branch" expands. Explain it. The --branch argument is not optional. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index c1ce26884e..664da8a988 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git check-ref-format' -'git check-ref-format' [--branch] +'git check-ref-format' --branch DESCRIPTION ----------- @@ -57,8 +57,11 @@ reference name expressions (see linkgit:git-rev-parse[1]): . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--branch` option, it expands a branch name shorthand and -prints the name of the branch the shorthand refers to. +With the `--branch` option, it expands the ``previous branch syntax'' +`@{-n}`. For example, `@{-1}` is a way to refer the last branch you +were on. This option should be used by porcelains to accept this +syntax anywhere a branch name is expected, so they can act as if you +typed the branch name. EXAMPLE ------- -- cgit v1.2.3 From 38eedc634bc5d30e8a7a2356d9eb3ae95d9b1d75 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 12 Oct 2009 16:39:43 -0700 Subject: git check-ref-format --print Tolerating empty path components in ref names means each ref does not have a unique name. This creates difficulty for porcelains that want to see if two branches are equal. Add a helper associating to each ref a canonical name. If a user asks a porcelain to create a ref "refs/heads//master", the porcelain can run "git check-ref-format --print refs/heads//master" and only deal with "refs/heads/master" from then on. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 0b7982ea76..211ae1c3fa 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git check-ref-format' +'git check-ref-format' --print 'git check-ref-format' [--branch] DESCRIPTION @@ -63,16 +64,28 @@ reference name expressions (see linkgit:git-rev-parse[1]): . at-open-brace `@{` is used as a notation to access a reflog entry. +With the `--print` option, if 'refname' is acceptable, it prints the +canonicalized name of a hypothetical reference with that name. That is, +it prints 'refname' with any extra `/` characters removed. + With the `--branch` option, it expands a branch name shorthand and prints the name of the branch the shorthand refers to. -EXAMPLE -------- - -git check-ref-format --branch @{-1}:: - -Print the name of the previous branch. +EXAMPLES +-------- +* Print the name of the previous branch: ++ +------------ +$ git check-ref-format --branch @{-1} +------------ + +* Determine the reference name to use for a new branch: ++ +------------ +$ ref=$(git check-ref-format --print "refs/heads/$newbranch") || +die "we do not like '$newbranch' as a branch name." +------------ GIT --- -- cgit v1.2.3 From 0b444cdb19bcfcc7f59b7b00783cbfbbc5ddcf63 Mon Sep 17 00:00:00 2001 From: Thomas Rast Date: Sun, 10 Jan 2010 00:33:00 +0100 Subject: Documentation: spell 'git cmd' without dash throughout The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH. --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 0aeef24780..d9a3326f58 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -60,7 +60,7 @@ reference name expressions (see linkgit:git-rev-parse[1]): . A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s value and store it in dstref" in fetch and push operations. It may also be used to select a specific object such as with - 'git-cat-file': "git cat-file blob v1.3.3:refs.c". + 'git cat-file': "git cat-file blob v1.3.3:refs.c". . at-open-brace `@{` is used as a notation to access a reflog entry. -- cgit v1.2.3 From 8ff883029a97b38b893b15199393d0e4e7190c0d Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 10 Feb 2010 10:18:55 -0800 Subject: check-ref-format documentation: fix enumeration mark-up The last item in the enumerated refname rule was mistakenly made into a sub-item of the 7th one. It should be the 8th one in the list on its own. Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 0aeef24780..3f7835f4a7 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -43,7 +43,7 @@ imposes the following rules on how references are named: . They cannot contain a sequence `@{`. -- They cannot contain a `\\`. +. They cannot contain a `\\`. These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used -- cgit v1.2.3 From 8222153d8449cb1d0f9c4b06b7f7f5b0c5128205 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 12 Feb 2010 15:39:03 -0800 Subject: Re-fix check-ref-format documentation mark-up It is not double-backslash we forbid; backslashes are forbidden since a4c2e699 (Disallow '\' in ref names, 2009-05-08) Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 3f7835f4a7..7422185bf5 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -43,7 +43,7 @@ imposes the following rules on how references are named: . They cannot contain a sequence `@{`. -. They cannot contain a `\\`. +. They cannot contain a `\`. These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used -- cgit v1.2.3 From cc1b8d8bc6e453b96798574d67ce9590eb3e82e1 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 17 Feb 2010 20:16:20 -0500 Subject: docs: don't talk about $GIT_DIR/refs/ everywhere It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we may also consult the packed refs mechanism. These days we tend to treat the "refs hierarchy" as more of an abstract namespace that happens to be represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at worst it can confuse users who then look in $GIT_DIR/refs and find that it is missing some of the refs they expected to see. This patch drops most uses of "$GIT_DIR/refs/*", changing them into just "refs/*", under the assumption that users can handle the concept of an abstract refs namespace. There are a few things to note: - most cases just dropped the $GIT_DIR/ portion. But for cases where that left _just_ the word "refs", I changed it to "refs/" to help indicate that it was a hierarchy. I didn't do the same for longer paths (e.g., "refs/heads" remained, instead of becoming "refs/heads/"). - in some cases, no change was made, as the text was explicitly about unpacked refs (e.g., the discussion in git-pack-refs). - In some cases it made sense instead to note the existence of packed refs (e.g., in check-ref-format and rev-parse). Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index e1c4320f02..379eee6734 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -19,8 +19,9 @@ 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. git -imposes the following rules on how references are named: +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). +git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) grouping, but no slash-separated component can begin with a -- cgit v1.2.3 From f028cdae6663166ebfd777e73aacce1f5e7159d6 Mon Sep 17 00:00:00 2001 From: Michael J Gruber Date: Mon, 5 Jul 2010 18:11:41 +0200 Subject: Documentation: link to gitrevisions rather than git-rev-parse Currently, whenever we need documentation for revisions and ranges, we link to the git-rev-parse man page, i.e. a plumbing man page, which has this along with the documentation of all rev-parse modes. Link to the new gitrevisions man page instead in all cases except - when the actual git-rev-parse command is referred to or - in very technical context (git-send-pack). Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 379eee6734..f5c2e0601d 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -49,7 +49,7 @@ git imposes the following rules on how references are named: These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain -reference name expressions (see linkgit:git-rev-parse[1]): +reference name expressions (see linkgit:gitrevisions[1]): . A double-dot `..` is often used as in `ref1..ref2`, and in some contexts this notation means `{caret}ref1 ref2` (i.e. not in -- cgit v1.2.3 From 9d83e3827fc1031bbcafb0d26128e95dda306aed Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 11 Oct 2010 11:03:32 -0500 Subject: Documentation: gitrevisions is in section 7 Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-check-ref-format.txt') diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index f5c2e0601d..205d83dd0b 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -49,7 +49,7 @@ git imposes the following rules on how references are named: These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain -reference name expressions (see linkgit:gitrevisions[1]): +reference name expressions (see linkgit:gitrevisions[7]): . A double-dot `..` is often used as in `ref1..ref2`, and in some contexts this notation means `{caret}ref1 ref2` (i.e. not in -- cgit v1.2.3