Merge branch 'jn/doc-backslash'
* jn/doc-backslash: Documentation: remove stray backslash in show-branch discussion Documentation: remove stray backslashes from "Fighting regressions" article Documentation: do not convert ... operator to ellipses Documentation: avoid stray backslash in user manual Documentation: avoid stray backslashes in core tutorial Documentation: remove stray backslashes in rev-parse manual Documentation: remove backslash before ~ in fast-import manual Documentation: remove stray backslash from "git bundle" manual Documentation/technical: avoid stray backslash in parse-options API docs Documentation: remove backslashes in manpage synopses Documentation: clarify quoting in gitignore docs Documentation: clarify quoting in "git rm" example Documentation: add missing quotes to "git grep" examples Documentation: clarify quoting in "git add" example Documentation: unbreak regex in show-ref manual Documentation: quoting trouble in "git rm" discussion Documentation: tweak description of log.date
This commit is contained in:
Junio C Hamano
commit
c0808fe708
@ -16,7 +16,9 @@ plus=+
|
||||
caret=^
|
||||
startsb=[
|
||||
endsb=]
|
||||
backslash=\
|
||||
tilde=~
|
||||
apostrophe='
|
||||
backtick=`
|
||||
|
||||
ifdef::backend-docbook[]
|
||||
|
||||
@ -1305,10 +1305,11 @@ interactive.singlekey::
|
||||
ignored if portable keystroke input is not available.
|
||||
|
||||
log.date::
|
||||
Set default date-time mode for the log command. Setting log.date
|
||||
value is similar to using 'git log'\'s --date option. The value is one of the
|
||||
following alternatives: {relative,local,default,iso,rfc,short}.
|
||||
See linkgit:git-log[1].
|
||||
Set the default date-time mode for the 'log' command.
|
||||
Setting a value for log.date is similar to using 'git log''s
|
||||
`\--date` option. Possible values are `relative`, `local`,
|
||||
`default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1]
|
||||
for details.
|
||||
|
||||
log.decorate::
|
||||
Print out the ref names of any commits that are shown by the log
|
||||
|
||||
@ -157,14 +157,14 @@ those in info/exclude. See linkgit:gitrepository-layout[5].
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
* Adds content from all `\*.txt` files under `Documentation` directory
|
||||
* Adds content from all `*.txt` files under `Documentation` directory
|
||||
and its subdirectories:
|
||||
+
|
||||
------------
|
||||
$ git add Documentation/\*.txt
|
||||
------------
|
||||
+
|
||||
Note that the asterisk `\*` is quoted from the shell in this
|
||||
Note that the asterisk `*` is quoted from the shell in this
|
||||
example; this lets the command include the files from
|
||||
subdirectories of `Documentation/` directory.
|
||||
|
||||
|
||||
@ -873,7 +873,7 @@ c * N * T + b * M * log2(M) tests
|
||||
where c is the number of rounds of test (so a small constant) and b is
|
||||
the ratio of bug per commit (hopefully a small constant too).
|
||||
|
||||
So of course it's much better as it's O(N \* T) vs O(N \* T \* M) if
|
||||
So of course it's much better as it's O(N * T) vs O(N * T * M) if
|
||||
you would test everything after each commit.
|
||||
|
||||
This means that test suites are good to prevent some bugs from being
|
||||
|
||||
@ -60,7 +60,7 @@ unbundle <file>::
|
||||
[git-rev-list-args...]::
|
||||
A list of arguments, acceptable to 'git rev-parse' and
|
||||
'git rev-list', that specifies the specific objects and references
|
||||
to transport. For example, `master\~10..master` causes the
|
||||
to transport. For example, `master~10..master` causes the
|
||||
current master reference to be packaged along with all objects
|
||||
added since its 10th ancestor commit. There is no explicit
|
||||
limit to the number of references and objects that may be
|
||||
@ -79,12 +79,12 @@ SPECIFYING REFERENCES
|
||||
|
||||
'git bundle' will only package references that are shown by
|
||||
'git show-ref': this includes heads, tags, and remote heads. References
|
||||
such as `master\~1` cannot be packaged, but are perfectly suitable for
|
||||
such as `master{tilde}1` cannot be packaged, but are perfectly suitable for
|
||||
defining the basis. More than one reference may be packaged, and more
|
||||
than one basis can be specified. The objects packaged are those not
|
||||
contained in the union of the given bases. Each basis can be
|
||||
specified explicitly (e.g. `^master\~10`), or implicitly (e.g.
|
||||
`master\~10..master`, `--since=10.days.ago master`).
|
||||
specified explicitly (e.g. `^master{tilde}10`), or implicitly (e.g.
|
||||
`master{tilde}10..master`, `--since=10.days.ago master`).
|
||||
|
||||
It is very important that the basis used be held by the destination.
|
||||
It is okay to err on the side of caution, causing the bundle file
|
||||
|
||||
@ -13,7 +13,7 @@ SYNOPSIS
|
||||
[--stage=<number>|all]
|
||||
[--temp]
|
||||
[-z] [--stdin]
|
||||
[--] [<file>]\*
|
||||
[--] [<file>]*
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -187,7 +187,7 @@ As a special case, the `"@\{-N\}"` syntax for the N-th last branch
|
||||
checks out the branch (instead of detaching). You may also specify
|
||||
`-` which is synonymous with `"@\{-1\}"`.
|
||||
+
|
||||
As a further special case, you may use `"A...B"` as a shortcut for the
|
||||
As a further special case, you may use `"A\...B"` as a shortcut for the
|
||||
merge base of `A` and `B` if there is exactly one merge base. You can
|
||||
leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
'git commit-tree' <tree> [-p <parent commit>]\* < changelog
|
||||
'git commit-tree' <tree> [-p <parent commit>]* < changelog
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -99,7 +99,7 @@ marks the same across runs.
|
||||
[git-rev-list-args...]::
|
||||
A list of arguments, acceptable to 'git rev-parse' and
|
||||
'git rev-list', that specifies the specific objects and references
|
||||
to export. For example, `master\~10..master` causes the
|
||||
to export. For example, `master{tilde}10..master` causes the
|
||||
current master reference to be exported along with all objects
|
||||
added since its 10th ancestor commit.
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
|
||||
[--sort=<key>]\* [--format=<format>] [<pattern>...]
|
||||
[--sort=<key>]* [--format=<format>] [<pattern>...]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -191,11 +191,11 @@ OPTIONS
|
||||
Examples
|
||||
--------
|
||||
|
||||
git grep 'time_t' \-- '*.[ch]'::
|
||||
git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}::
|
||||
Looks for `time_t` in all tracked .c and .h files in the working
|
||||
directory and its subdirectories.
|
||||
|
||||
git grep -e \'#define\' --and \( -e MAX_PATH -e PATH_MAX \)::
|
||||
git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)::
|
||||
Looks for a line that has `#define` and either `MAX_PATH` or
|
||||
`PATH_MAX`.
|
||||
|
||||
|
||||
@ -10,14 +10,14 @@ SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git ls-files' [-z] [-t] [-v]
|
||||
(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
|
||||
(-[c|d|o|i|s|u|k|m])\*
|
||||
(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
|
||||
(-[c|d|o|i|s|u|k|m])*
|
||||
[-x <pattern>|--exclude=<pattern>]
|
||||
[-X <file>|--exclude-from=<file>]
|
||||
[--exclude-per-directory=<file>]
|
||||
[--exclude-standard]
|
||||
[--error-unmatch] [--with-tree=<tree-ish>]
|
||||
[--full-name] [--abbrev] [--] [<file>]\*
|
||||
[--full-name] [--abbrev] [--] [<file>]*
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*)
|
||||
'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -200,7 +200,7 @@ summary::
|
||||
For a successfully pushed ref, the summary shows the old and new
|
||||
values of the ref in a form suitable for using as an argument to
|
||||
`git log` (this is `<old>..<new>` in most cases, and
|
||||
`<old>...<new>` for forced non-fast-forward updates).
|
||||
`<old>\...<new>` for forced non-fast-forward updates).
|
||||
+
|
||||
For a failed update, more details are given:
|
||||
+
|
||||
|
||||
@ -210,7 +210,7 @@ OPTIONS
|
||||
<upstream>. May be any valid commit, and not just an
|
||||
existing branch name.
|
||||
+
|
||||
As a special case, you may use "A...B" as a shortcut for the
|
||||
As a special case, you may use "A\...B" as a shortcut for the
|
||||
merge base of A and B if there is exactly one merge base. You can
|
||||
leave out at most one of A and B, in which case it defaults to HEAD.
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
'git relink' [--safe] <dir> [<dir>]\* <master_dir>
|
||||
'git relink' [--safe] <dir> [<dir>]* <master_dir>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -74,7 +74,7 @@ OPTIONS
|
||||
properly quoted for consumption by shell. Useful when
|
||||
you expect your parameter to contain whitespaces and
|
||||
newlines (e.g. when using pickaxe `-S` with
|
||||
'git diff-\*'). In contrast to the `--sq-quote` option,
|
||||
'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
|
||||
the command input is still interpreted as usual.
|
||||
|
||||
--not::
|
||||
@ -112,14 +112,15 @@ OPTIONS
|
||||
+
|
||||
If a `pattern` is given, only refs matching the given shell glob are
|
||||
shown. If the pattern does not contain a globbing character (`?`,
|
||||
`\*`, or `[`), it is turned into a prefix match by appending `/\*`.
|
||||
`{asterisk}`, or `[`), it is turned into a prefix match by
|
||||
appending `/{asterisk}`.
|
||||
|
||||
--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 (`?`, `\*`, or `[`), it is turned into a prefix
|
||||
match by appending `/\*`.
|
||||
character (`?`, `{asterisk}`, or `[`), it is turned into a prefix
|
||||
match by appending `/{asterisk}`.
|
||||
|
||||
--show-toplevel::
|
||||
Show the absolute path of the top-level directory.
|
||||
|
||||
@ -78,7 +78,8 @@ a file that you have not told git about does not remove that file.
|
||||
|
||||
File globbing matches across directory boundaries. Thus, given
|
||||
two directories `d` and `d2`, there is a difference between
|
||||
using `git rm \'d\*\'` and `git rm \'d/\*\'`, as the former will
|
||||
using `git rm {apostrophe}d{asterisk}{apostrophe}` and
|
||||
`git rm {apostrophe}d/{asterisk}{apostrophe}`, as the former will
|
||||
also remove all of directory `d2`.
|
||||
|
||||
REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM
|
||||
@ -135,11 +136,11 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
git rm Documentation/\\*.txt::
|
||||
Removes all `\*.txt` files from the index that are under the
|
||||
git rm Documentation/\*.txt::
|
||||
Removes all `*.txt` files from the index that are under the
|
||||
`Documentation` directory and any of its subdirectories.
|
||||
+
|
||||
Note that the asterisk `\*` is quoted from the shell in this
|
||||
Note that the asterisk `*` is quoted from the shell in this
|
||||
example; this lets git, and not the shell, expand the pathnames
|
||||
of files and subdirectories under the `Documentation/` directory.
|
||||
|
||||
|
||||
@ -168,10 +168,10 @@ $ git show-branch master fixes mhf
|
||||
------------------------------------------------
|
||||
|
||||
These three branches all forked from a common commit, [master],
|
||||
whose commit message is "Add \'git show-branch\'". The "fixes"
|
||||
branch adds one commit "Introduce "reset type" flag to "git reset"".
|
||||
The "mhf" branch adds many other commits. The current branch
|
||||
is "master".
|
||||
whose commit message is "Add {apostrophe}git show-branch{apostrophe}".
|
||||
The "fixes" branch adds one commit "Introduce "reset type" flag to
|
||||
"git reset"". The "mhf" branch adds many other commits.
|
||||
The current branch is "master".
|
||||
|
||||
|
||||
EXAMPLE
|
||||
|
||||
@ -73,8 +73,8 @@ OPTIONS
|
||||
--exclude-existing[=<pattern>]::
|
||||
|
||||
Make 'git show-ref' act as a filter that reads refs from stdin of the
|
||||
form "^(?:<anything>\s)?<refname>(?:\^\{\})?$" and performs the
|
||||
following actions on each:
|
||||
form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$"
|
||||
and performs the following actions on each:
|
||||
(1) strip "^{}" at the end of line if any;
|
||||
(2) ignore if pattern is provided and does not head-match refname;
|
||||
(3) warn if refname is not a well-formed refname and skip;
|
||||
|
||||
@ -12,7 +12,7 @@ SYNOPSIS
|
||||
'git update-index'
|
||||
[--add] [--remove | --force-remove] [--replace]
|
||||
[--refresh] [-q] [--unmerged] [--ignore-missing]
|
||||
[--cacheinfo <mode> <object> <file>]\*
|
||||
[--cacheinfo <mode> <object> <file>]*
|
||||
[--chmod=(+|-)x]
|
||||
[--assume-unchanged | --no-assume-unchanged]
|
||||
[--skip-worktree | --no-skip-worktree]
|
||||
@ -21,7 +21,7 @@ SYNOPSIS
|
||||
[--info-only] [--index-info]
|
||||
[-z] [--stdin]
|
||||
[--verbose]
|
||||
[--] [<file>]\*
|
||||
[--] [<file>]*
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
@ -110,7 +110,7 @@ An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
|
||||
and a reference to an object is always the 40-byte hex
|
||||
representation of that SHA1 name. The files in the `refs`
|
||||
subdirectory are expected to contain these hex references
|
||||
(usually with a final `\'\n\'` at the end), and you should thus
|
||||
(usually with a final `\n` at the end), and you should thus
|
||||
expect to see a number of 41-byte files containing these
|
||||
references in these `refs` subdirectories when you actually start
|
||||
populating your tree.
|
||||
@ -310,7 +310,7 @@ and this will just output the name of the resulting tree, in this case
|
||||
----------------
|
||||
|
||||
which is another incomprehensible object name. Again, if you want to,
|
||||
you can use `git cat-file -t 8988d\...` to see that this time the object
|
||||
you can use `git cat-file -t 8988d...` to see that this time the object
|
||||
is not a "blob" object, but a "tree" object (you can also use
|
||||
`git cat-file` to actually output the raw object contents, but you'll see
|
||||
mainly a binary mess, so that's less interesting).
|
||||
@ -436,8 +436,8 @@ $ git update-index hello
|
||||
(note how we didn't need the `\--add` flag this time, since git knew
|
||||
about the file already).
|
||||
|
||||
Note what happens to the different 'git diff-\*' versions here. After
|
||||
we've updated `hello` in the index, `git diff-files -p` now shows no
|
||||
Note what happens to the different 'git diff-{asterisk}' versions here.
|
||||
After we've updated `hello` in the index, `git diff-files -p` now shows no
|
||||
differences, but `git diff-index -p HEAD` still *does* show that the
|
||||
current state is different from the state we committed. In fact, now
|
||||
'git diff-index' shows the same difference whether we use the `--cached`
|
||||
@ -494,7 +494,7 @@ and it will show what the last commit (in `HEAD`) actually changed.
|
||||
[NOTE]
|
||||
============
|
||||
Here is an ASCII art by Jon Loeliger that illustrates how
|
||||
various diff-\* commands compare things.
|
||||
various 'diff-{asterisk}' commands compare things.
|
||||
|
||||
diff-tree
|
||||
+----+
|
||||
@ -958,11 +958,11 @@ $ git show-branch --topo-order --more=1 master mybranch
|
||||
The first two lines indicate that it is showing the two branches
|
||||
and the first line of the commit log message from their
|
||||
top-of-the-tree commits, you are currently on `master` branch
|
||||
(notice the asterisk `\*` character), and the first column for
|
||||
(notice the asterisk `{asterisk}` character), and the first column for
|
||||
the later output lines is used to show commits contained in the
|
||||
`master` branch, and the second column for the `mybranch`
|
||||
branch. Three commits are shown along with their log messages.
|
||||
All of them have non blank characters in the first column (`*`
|
||||
All of them have non blank characters in the first column (`{asterisk}`
|
||||
shows an ordinary commit on the current branch, `-` is a merge commit), which
|
||||
means they are now part of the `master` branch. Only the "Some
|
||||
work" commit has the plus `+` character in the second column,
|
||||
@ -1092,7 +1092,7 @@ Downloader from http and https URL
|
||||
first obtains the topmost commit object name from the remote site
|
||||
by looking at the specified refname under `repo.git/refs/` directory,
|
||||
and then tries to obtain the
|
||||
commit object by downloading from `repo.git/objects/xx/xxx\...`
|
||||
commit object by downloading from `repo.git/objects/xx/xxx...`
|
||||
using the object name of that commit object. Then it reads the
|
||||
commit object to find out its parent commits and the associate
|
||||
tree object; it repeats this process until it gets all the
|
||||
@ -1420,7 +1420,7 @@ packed, and stores the packed file in `.git/objects/pack`
|
||||
directory.
|
||||
|
||||
[NOTE]
|
||||
You will see two files, `pack-\*.pack` and `pack-\*.idx`,
|
||||
You will see two files, `pack-{asterisk}.pack` and `pack-{asterisk}.idx`,
|
||||
in `.git/objects/pack` directory. They are closely related to
|
||||
each other, and if you ever copy them by hand to a different
|
||||
repository for whatever reason, you should make sure you copy
|
||||
|
||||
@ -90,12 +90,12 @@ Patterns have the following format:
|
||||
- Otherwise, git treats the pattern as a shell glob suitable
|
||||
for consumption by fnmatch(3) with the FNM_PATHNAME flag:
|
||||
wildcards in the pattern will not match a / in the pathname.
|
||||
For example, "Documentation/\*.html" matches
|
||||
For example, "Documentation/{asterisk}.html" matches
|
||||
"Documentation/git.html" but not "Documentation/ppc/ppc.html"
|
||||
or "tools/perf/Documentation/perf.html".
|
||||
|
||||
- A leading slash matches the beginning of the pathname.
|
||||
For example, "/*.c" matches "cat-file.c" but not
|
||||
For example, "/{asterisk}.c" matches "cat-file.c" but not
|
||||
"mozilla-sha1/sha1.c".
|
||||
|
||||
An example:
|
||||
|
||||
@ -321,7 +321,7 @@ excluded from the output.
|
||||
reflog entries from the most recent one to older ones.
|
||||
When this option is used you cannot specify commits to
|
||||
exclude (that is, '{caret}commit', 'commit1..commit2',
|
||||
nor 'commit1...commit2' notations cannot be used).
|
||||
nor 'commit1\...commit2' notations cannot be used).
|
||||
+
|
||||
With '\--pretty' format other than oneline (for obvious reasons),
|
||||
this causes the output to have two extra lines of information
|
||||
|
||||
@ -201,7 +201,7 @@ The last element of the array must be `OPT_END()`.
|
||||
If not stated otherwise, interpret the arguments as follows:
|
||||
|
||||
* `short` is a character for the short option
|
||||
(e.g. `\'e\'` for `-e`, use `0` to omit),
|
||||
(e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
|
||||
|
||||
* `long` is a string for the long option
|
||||
(e.g. `"example"` for `\--example`, use `NULL` to omit),
|
||||
@ -228,10 +228,10 @@ The function must be defined in this form:
|
||||
The callback mechanism is as follows:
|
||||
|
||||
* Inside `func`, the only interesting member of the structure
|
||||
given by `opt` is the void pointer `opt->value`.
|
||||
`\*opt->value` will be the value that is saved into `var`, if you
|
||||
given by `opt` is the void pointer `opt\->value`.
|
||||
`\*opt\->value` will be the value that is saved into `var`, if you
|
||||
use `OPT_CALLBACK()`.
|
||||
For example, do `*(unsigned long *)opt->value = 42;` to get 42
|
||||
For example, do `*(unsigned long *)opt\->value = 42;` to get 42
|
||||
into an `unsigned long` variable.
|
||||
|
||||
* Return value `0` indicates success and non-zero return
|
||||
|
||||
@ -4251,9 +4251,9 @@ Two things are interesting here:
|
||||
negative numbers in case of different errors--and 0 on success.
|
||||
|
||||
- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
|
||||
char \*`, but is actually expected to be a pointer to `unsigned
|
||||
char {asterisk}`, but is actually expected to be a pointer to `unsigned
|
||||
char[20]`. This variable will contain the 160-bit SHA-1 of the given
|
||||
commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it
|
||||
commit. Note that whenever a SHA-1 is passed as `unsigned char {asterisk}`, it
|
||||
is the binary representation, as opposed to the ASCII representation in
|
||||
hex characters, which is passed as `char *`.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user