From 6cf378f0cbe7c7f944637892caeb9058c90a185a Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 Apr 2012 04:51:57 -0400 Subject: docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: foo bar which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor ` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 8023dc086d..f63b81aad6 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -113,15 +113,14 @@ OPTIONS + If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, -`{asterisk}`, or `[`), it is turned into a prefix match by -appending `/{asterisk}`. +`*`, or `[`), it is turned into a prefix match by appending `/*`. --glob=pattern:: Show all refs matching the shell glob pattern `pattern`. If the pattern does not start with `refs/`, this is automatically prepended. If the pattern does not contain a globbing - character (`?`, `{asterisk}`, or `[`), it is turned into a prefix - match by appending `/{asterisk}`. + character (`?`, `*`, or `[`), it is turned into a prefix + match by appending `/*`. --show-toplevel:: Show the absolute path of the top-level directory. -- cgit v1.2.1 From d0740ce0ba9417c34e00b5a61161d84f85ba7fbc Mon Sep 17 00:00:00 2001 From: Jon Seymour Date: Fri, 18 May 2012 19:23:24 +1000 Subject: rev-parse doc: --git-dir does not always show a relative path The description was misleading because it lead the reader to believe that --git-dir would always show a relative path when, in fact, the actual behaviour does not guarantee this. Rather, it was intended that the advice be given that if a relative path is shown, then the path is relative to the current working directory and not some other directory (for example, the root of the working tree). Signed-off-by: Jon Seymour Acked-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index ff23cb0219..00e73c84c7 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -137,7 +137,8 @@ appending `/{asterisk}`. --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to - the .git directory, relative to the current directory. + the .git directory. The path shown, when relative, is + relative to the current working directory. + If `$GIT_DIR` is not defined and the current directory is not detected to lie in a git repository or work tree -- cgit v1.2.1 From 957d74062c1f0e92368aeda335e27d2d61f584f6 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 3 Jul 2012 14:21:59 -0700 Subject: rev-parse --disambiguate= The new option allows you to feed an ambiguous prefix and enumerate all the objects that share it as a prefix of their object names. Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 8023dc086d..8d90863ee3 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -101,6 +101,12 @@ OPTIONS The option core.warnAmbiguousRefs is used to select the strict abbreviation mode. +--disambiguate=:: + Show every object whose name begins with the given prefix. + The must be at least 4 hexadecimal digits long to + avoid listing each and every object in the repository by + mistake. + --all:: Show all refs found in `refs/`. -- cgit v1.2.1 From 2de9b71138171dca7279db3b3fe67e868c76d921 Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Mon, 21 Jan 2013 20:17:53 +0100 Subject: Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 3c63561f02..c7434697ef 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Many git porcelainish commands take mixture of flags +Many Git porcelainish commands take mixture of flags (i.e. parameters that begin with a dash '-') and parameters meant for the underlying 'git rev-list' command they use internally and flags and parameters for the other commands they use @@ -147,7 +147,7 @@ shown. If the pattern does not contain a globbing character (`?`, relative to the current working directory. + If `$GIT_DIR` is not defined and the current directory -is not detected to lie in a git repository or work tree +is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. --is-inside-git-dir:: -- cgit v1.2.1 From 0859c969db9d1250cbdb14d34efa1d17209ff45b Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Fri, 1 Feb 2013 19:07:56 +0100 Subject: Documentation: do not use undefined terms git-dir and git-file We will add gitfile to the glossary in a separate commit. Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index c7434697ef..10a116faf8 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -187,9 +187,11 @@ print a message to stderr and exit with nonzero status. Flags and parameters to be parsed. --resolve-git-dir :: - Check if is a valid git-dir or a git-file pointing to a valid - git-dir. If is a valid git-dir the resolved path to git-dir will - be printed. + Check if is a valid repository or a gitfile that + points at a valid repository, and print the location of the + repository. If is a gitfile then the resolved path + to the real repository is printed. + include::revisions.txt[] -- cgit v1.2.1 From 2db60670ba0c6dcaa42ed420f337851eea800bbc Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 30 Mar 2013 07:44:25 +0100 Subject: rev-parse: clarify documentation for the --verify option The old version could be read to mean that the argument has to refer to a valid object, but that is incorrect: * the object is not necessarily read (e.g., to check for corruption) * if the argument is a 40-digit string of hex digits, then it is accepted whether or not is is the name of an existing object. So reword the explanation to be less ambiguous. Also fix the examples involving --verify: to be sure that the argument refers to a commit (rather than some other kind of object), the argument has to be suffixed with "^{commit}". This trick is not possible in the example involving --default, so don't imply that it is exactly the same as the previous example. Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 3c63561f02..757d195962 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -60,8 +60,19 @@ OPTIONS instead. --verify:: - The parameter given must be usable as a single, valid - object name. Otherwise barf and abort. + Verify that exactly one parameter is provided, and that it + can be turned into a raw 20-byte SHA-1 that can be used to + access the object database. If so, emit it to the standard + output; otherwise, error out. ++ +If you want to make sure that the output actually names an object in +your object database and/or can be used as a specific type of object +you require, you can add "^{type}" peeling operator to the parmeter. +For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` +names an existing object that is a commit-ish (i.e. a commit, or an +annotated tag that points at a commit). To make sure that `$VAR` +names an existing object of any type, `git rev-parse "$VAR^{object}"` +can be used. -q:: --quiet:: @@ -306,12 +317,12 @@ $ git rev-parse --verify HEAD * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ git rev-parse --verify $REV +$ git rev-parse --verify $REV^{commit} ------------ + This will error out if $REV is empty or not a valid revision. -* Same as above: +* Similar to above: + ------------ $ git rev-parse --default master --verify $REV -- cgit v1.2.1 From d5fa1f1a69f578831179b77893aac480b986e875 Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Mon, 15 Apr 2013 19:49:04 +0200 Subject: The name of the hash function is "SHA-1", not "SHA1" Use "SHA-1" instead of "SHA1" whenever we talk about the hash function. When used as a programming symbol, we keep "SHA1". Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 10a116faf8..f2537bb837 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -84,7 +84,7 @@ OPTIONS one. --symbolic:: - Usually the object names are output in SHA1 form (with + Usually the object names are output in SHA-1 form (with possible '{caret}' prefix); this option makes them output in a form as close to the original input as possible. @@ -169,7 +169,7 @@ print a message to stderr and exit with nonzero status. --short:: --short=number:: - Instead of outputting the full SHA1 values of object names try to + Instead of outputting the full SHA-1 values of object names try to abbreviate them to a shorter unique name. When no length is specified 7 is used. The minimum length is 4. -- cgit v1.2.1 From 12b9d32790b40bf3ea49134095619700191abf1f Mon Sep 17 00:00:00 2001 From: John Keeping Date: Sun, 16 Jun 2013 15:18:17 +0100 Subject: rev-parse: add --prefix option This makes 'git rev-parse' behave as if it were invoked from the specified subdirectory of a repository, with the difference that any file paths which it prints are prefixed with the full path from the top of the working tree. This is useful for shell scripts where we may want to cd to the top of the working tree but need to handle relative paths given by the user on the command line. Signed-off-by: John Keeping Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 947d62fd25..993903c9f1 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -59,6 +59,22 @@ OPTIONS If there is no parameter given by the user, use `` instead. +--prefix :: + Behave as if 'git rev-parse' was invoked from the `` + subdirectory of the working tree. Any relative filenames are + resolved as if they are prefixed by `` and will be printed + in that form. ++ +This can be used to convert arguments to a command run in a subdirectory +so that they can still be used after moving to the top-level of the +repository. For example: ++ +---- +prefix=$(git rev-parse --show-prefix) +cd "$(git rev-parse --show-toplevel)" +eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" +---- + --verify:: Verify that exactly one parameter is provided, and that it can be turned into a raw 20-byte SHA-1 that can be used to -- cgit v1.2.1 From 17b83d71d52a5eb6a621be22daa624414d3ee514 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20B=C3=ADlka?= Date: Mon, 22 Jul 2013 23:02:23 +0200 Subject: typofix: documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Ondřej Bílka Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-rev-parse.txt') diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 993903c9f1..2b126c0a77 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -83,7 +83,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "^{type}" peeling operator to the parmeter. +you require, you can add "^{type}" peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` -- cgit v1.2.1