Commit 6cf378f0 authored by Jeff King's avatar Jeff King Committed by Junio C Hamano

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:

      <tt><sub></tt> foo <tt></sub>bar</tt>

    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 <[email protected]>` used to
    erroneously auto-generate a mailto footnote for
    [email protected]

  - 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.<url>.\*`

    properly escaped the asterisk in the first case, but
    literally passed through the backslash in the second
    case.
Signed-off-by: default avatarJeff King <[email protected]>
Signed-off-by: default avatarJunio C Hamano <[email protected]>
parent 868d6623
...@@ -82,7 +82,7 @@ endif ...@@ -82,7 +82,7 @@ endif
# #
ifndef ASCIIDOC7 ifndef ASCIIDOC7
ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal ASCIIDOC_EXTRA += -a asciidoc7compatible
endif endif
ifdef DOCBOOK_XSL_172 ifdef DOCBOOK_XSL_172
ASCIIDOC_EXTRA += -a git-asciidoc-no-roff ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
......
...@@ -463,8 +463,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. ...@@ -463,8 +463,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
core.excludesfile:: core.excludesfile::
In addition to '.gitignore' (per-directory) and In addition to '.gitignore' (per-directory) and
'.git/info/exclude', git looks into this file for patterns '.git/info/exclude', git looks into this file for patterns
of files which are not meant to be tracked. "{tilde}/" is expanded of files which are not meant to be tracked. "`~/`" is expanded
to the value of `$HOME` and "{tilde}user/" to the specified user's to the value of `$HOME` and "`~user/`" to the specified user's
home directory. See linkgit:gitignore[5]. home directory. See linkgit:gitignore[5].
core.askpass:: core.askpass::
...@@ -845,7 +845,7 @@ commit.status:: ...@@ -845,7 +845,7 @@ commit.status::
commit.template:: commit.template::
Specify a file to use as the template for new commit messages. Specify a file to use as the template for new commit messages.
"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the
specified user's home directory. specified user's home directory.
credential.helper:: credential.helper::
...@@ -970,7 +970,7 @@ format.thread:: ...@@ -970,7 +970,7 @@ format.thread::
a boolean value, or `shallow` or `deep`. `shallow` threading a boolean value, or `shallow` or `deep`. `shallow` threading
makes every mail a reply to the head of the series, makes every mail a reply to the head of the series,
where the head is chosen from the cover letter, the where the head is chosen from the cover letter, the
`\--in-reply-to`, and the first patch mail, in this order. `--in-reply-to`, and the first patch mail, in this order.
`deep` threading makes every mail a reply to the previous one. `deep` threading makes every mail a reply to the previous one.
A true boolean value is the same as `shallow`, and a false A true boolean value is the same as `shallow`, and a false
value disables threading. value disables threading.
...@@ -1401,7 +1401,7 @@ instaweb.port:: ...@@ -1401,7 +1401,7 @@ instaweb.port::
interactive.singlekey:: interactive.singlekey::
In interactive commands, allow the user to provide one-letter In interactive commands, allow the user to provide one-letter
input with a single key (i.e., without hitting enter). input with a single key (i.e., without hitting enter).
Currently this is used by the `\--patch` mode of Currently this is used by the `--patch` mode of
linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1],
linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this
setting is silently ignored if portable keystroke input setting is silently ignored if portable keystroke input
...@@ -1409,13 +1409,13 @@ interactive.singlekey:: ...@@ -1409,13 +1409,13 @@ interactive.singlekey::
log.abbrevCommit:: log.abbrevCommit::
If true, makes linkgit:git-log[1], linkgit:git-show[1], and If true, makes linkgit:git-log[1], linkgit:git-show[1], and
linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
override this option with `\--no-abbrev-commit`. override this option with `--no-abbrev-commit`.
log.date:: log.date::
Set the default date-time mode for the 'log' command. Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s Setting a value for log.date is similar to using 'git log''s
`\--date` option. Possible values are `relative`, `local`, `--date` option. Possible values are `relative`, `local`,
`default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1]
for details. for details.
...@@ -1605,18 +1605,18 @@ pack.indexVersion:: ...@@ -1605,18 +1605,18 @@ pack.indexVersion::
and this config option ignored whenever the corresponding pack is and this config option ignored whenever the corresponding pack is
larger than 2 GB. larger than 2 GB.
+ +
If you have an old git that does not understand the version 2 `{asterisk}.idx` file, If you have an old git that does not understand the version 2 `*.idx` file,
cloning or fetching over a non native protocol (e.g. "http" and "rsync") cloning or fetching over a non native protocol (e.g. "http" and "rsync")
that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the that will copy both `*.pack` file and corresponding `*.idx` file from the
other side may give you a repository that cannot be accessed with your other side may give you a repository that cannot be accessed with your
older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however, older version of git. If the `*.pack` file is smaller than 2 GB, however,
you can use linkgit:git-index-pack[1] on the *.pack file to regenerate you can use linkgit:git-index-pack[1] on the *.pack file to regenerate
the `{asterisk}.idx` file. the `*.idx` file.
pack.packSizeLimit:: pack.packSizeLimit::
The maximum size of a pack. This setting only affects The maximum size of a pack. This setting only affects
packing to a file when repacking, i.e. the git:// protocol packing to a file when repacking, i.e. the git:// protocol
is unaffected. It can be overridden by the `\--max-pack-size` is unaffected. It can be overridden by the `--max-pack-size`
option of linkgit:git-repack[1]. The minimum size allowed is option of linkgit:git-repack[1]. The minimum size allowed is
limited to 1 MiB. The default is unlimited. limited to 1 MiB. The default is unlimited.
Common unit suffixes of 'k', 'm', or 'g' are Common unit suffixes of 'k', 'm', or 'g' are
...@@ -1626,8 +1626,8 @@ pager.<cmd>:: ...@@ -1626,8 +1626,8 @@ pager.<cmd>::
If the value is boolean, turns on or off pagination of the If the value is boolean, turns on or off pagination of the
output of a particular git subcommand when writing to a tty. output of a particular git subcommand when writing to a tty.
Otherwise, turns on pagination for the subcommand using the Otherwise, turns on pagination for the subcommand using the
pager specified by the value of `pager.<cmd>`. If `\--paginate` pager specified by the value of `pager.<cmd>`. If `--paginate`
or `\--no-pager` is specified on the command line, it takes or `--no-pager` is specified on the command line, it takes
precedence over this option. To disable pagination for all precedence over this option. To disable pagination for all
commands, set `core.pager` or `GIT_PAGER` to `cat`. commands, set `core.pager` or `GIT_PAGER` to `cat`.
...@@ -1635,9 +1635,9 @@ pretty.<name>:: ...@@ -1635,9 +1635,9 @@ pretty.<name>::
Alias for a --pretty= format string, as specified in Alias for a --pretty= format string, as specified in
linkgit:git-log[1]. Any aliases defined here can be used just linkgit:git-log[1]. Any aliases defined here can be used just
as the built-in pretty formats could. For example, as the built-in pretty formats could. For example,
running `git config pretty.changelog "format:{asterisk} %H %s"` running `git config pretty.changelog "format:* %H %s"`
would cause the invocation `git log --pretty=changelog` would cause the invocation `git log --pretty=changelog`
to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. to be equivalent to running `git log "--pretty=format:* %H %s"`.
Note that an alias with the same name as a built-in format Note that an alias with the same name as a built-in format
will be silently ignored. will be silently ignored.
...@@ -1750,7 +1750,7 @@ remote.<name>.push:: ...@@ -1750,7 +1750,7 @@ remote.<name>.push::
remote.<name>.mirror:: remote.<name>.mirror::
If true, pushing to this remote will automatically behave If true, pushing to this remote will automatically behave
as if the `\--mirror` option was given on the command line. as if the `--mirror` option was given on the command line.
remote.<name>.skipDefaultUpdate:: remote.<name>.skipDefaultUpdate::
If true, this remote will be skipped by default when updating If true, this remote will be skipped by default when updating
......
...@@ -175,7 +175,7 @@ In the above example output, the function signature was changed ...@@ -175,7 +175,7 @@ In the above example output, the function signature was changed
from both files (hence two `-` removals from both file1 and from both files (hence two `-` removals from both file1 and
file2, plus `++` to mean one line that was added does not appear file2, plus `++` to mean one line that was added does not appear
in either file1 nor file2). Also eight other lines are the same in either file1 nor file2). Also eight other lines are the same
from file1 but do not appear in file2 (hence prefixed with `{plus}`). from file1 but do not appear in file2 (hence prefixed with `+`).
When shown by `git diff-tree -c`, it compares the parents of a When shown by `git diff-tree -c`, it compares the parents of a
merge commit with the merge result (i.e. file1..fileN are the merge commit with the merge result (i.e. file1..fileN are the
......
...@@ -74,7 +74,7 @@ These parameters can also be set individually with `--stat-width=<width>`, ...@@ -74,7 +74,7 @@ These parameters can also be set individually with `--stat-width=<width>`,
`--stat-name-width=<name-width>` and `--stat-count=<count>`. `--stat-name-width=<name-width>` and `--stat-count=<count>`.
--numstat:: --numstat::
Similar to `\--stat`, but shows number of added and Similar to `--stat`, but shows number of added and
deleted lines in decimal notation and pathname without deleted lines in decimal notation and pathname without
abbreviation, to make it more machine friendly. For abbreviation, to make it more machine friendly. For
binary files, outputs two `-` instead of saying binary files, outputs two `-` instead of saying
......
...@@ -98,8 +98,8 @@ you originally wrote. ...@@ -98,8 +98,8 @@ you originally wrote.
<9> switch to the master branch. <9> switch to the master branch.
<10> merge a topic branch into your master branch. <10> merge a topic branch into your master branch.
<11> review commit logs; other forms to limit output can be <11> review commit logs; other forms to limit output can be
combined and include `\--max-count=10` (show 10 commits), combined and include `--max-count=10` (show 10 commits),
`\--until=2005-12-10`, etc. `--until=2005-12-10`, etc.
<12> view only the changes that touch what's in `curses/` <12> view only the changes that touch what's in `curses/`
directory, since `v2.43` tag. directory, since `v2.43` tag.
......
...@@ -160,7 +160,7 @@ EXAMPLES ...@@ -160,7 +160,7 @@ EXAMPLES
Same as above, but the format is inferred from the output file. Same as above, but the format is inferred from the output file.
`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`:: `git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz`::
Create a compressed tarball for v1.4.0 release, but without a Create a compressed tarball for v1.4.0 release, but without a
global extended pax header. global extended pax header.
......
...@@ -160,7 +160,7 @@ introduced the file with: ...@@ -160,7 +160,7 @@ introduced the file with:
git log --diff-filter=A --pretty=short -- foo git log --diff-filter=A --pretty=short -- foo
and then annotate the change between the commit and its and then annotate the change between the commit and its
parents, using `commit{caret}!` notation: parents, using `commit^!` notation:
git blame -C -C -f $commit^! -- foo git blame -C -C -f $commit^! -- foo
......
...@@ -61,7 +61,7 @@ unbundle <file>:: ...@@ -61,7 +61,7 @@ unbundle <file>::
A list of arguments, acceptable to 'git rev-parse' and A list of arguments, acceptable to 'git rev-parse' and
'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES
below), that specifies the specific objects and references below), that specifies the specific objects and references
to transport. For example, `master{tilde}10..master` causes the to transport. For example, `master~10..master` causes the
current master reference to be packaged along with all objects current master reference to be packaged along with all objects
added since its 10th ancestor commit. There is no explicit added since its 10th ancestor commit. There is no explicit
limit to the number of references and objects that may be limit to the number of references and objects that may be
...@@ -80,12 +80,12 @@ SPECIFYING REFERENCES ...@@ -80,12 +80,12 @@ SPECIFYING REFERENCES
'git bundle' will only package references that are shown by 'git bundle' will only package references that are shown by
'git show-ref': this includes heads, tags, and remote heads. References 'git show-ref': this includes heads, tags, and remote heads. References
such as `master{tilde}1` cannot be packaged, but are perfectly suitable for such as `master~1` cannot be packaged, but are perfectly suitable for
defining the basis. More than one reference may be packaged, and more defining the basis. More than one reference may be packaged, and more
than one basis can be specified. The objects packaged are those not than one basis can be specified. The objects packaged are those not
contained in the union of the given bases. Each basis can be contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master{tilde}10`), or implicitly (e.g. specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master{tilde}10..master`, `--since=10.days.ago master`). `master~10..master`, `--since=10.days.ago master`).
It is very important that the basis used be held by the destination. 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 It is okay to err on the side of caution, causing the bundle file
......
...@@ -40,9 +40,9 @@ git imposes the following rules on how references are named: ...@@ -40,9 +40,9 @@ git imposes the following rules on how references are named:
. They cannot have ASCII control characters (i.e. bytes whose . They cannot have ASCII control characters (i.e. bytes whose
values are lower than \040, or \177 `DEL`), space, tilde `~`, values are lower than \040, or \177 `DEL`), space, tilde `~`,
caret `{caret}`, or colon `:` anywhere. caret `^`, or colon `:` anywhere.
. They cannot have question-mark `?`, asterisk `{asterisk}`, or open . They cannot have question-mark `?`, asterisk `*`, or open
bracket `[` anywhere. See the `--refspec-pattern` option below for bracket `[` anywhere. See the `--refspec-pattern` option below for
an exception to this rule. an exception to this rule.
...@@ -62,10 +62,10 @@ unquoted (by mistake), and also avoids ambiguities in certain ...@@ -62,10 +62,10 @@ unquoted (by mistake), and also avoids ambiguities in certain
reference name expressions (see linkgit:gitrevisions[7]): reference name expressions (see linkgit:gitrevisions[7]):
. A double-dot `..` is often used as in `ref1..ref2`, and in some . A double-dot `..` is often used as in `ref1..ref2`, and in some
contexts this notation means `{caret}ref1 ref2` (i.e. not in contexts this notation means `^ref1 ref2` (i.e. not in
`ref1` and in `ref2`). `ref1` and in `ref2`).
. A tilde `~` and caret `{caret}` are used to introduce the postfix . A tilde `~` and caret `^` are used to introduce the postfix
'nth parent' and 'peel onion' operation. 'nth parent' and 'peel onion' operation.
. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s . A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
...@@ -92,9 +92,9 @@ OPTIONS ...@@ -92,9 +92,9 @@ OPTIONS
--refspec-pattern:: --refspec-pattern::
Interpret <refname> as a reference name pattern for a refspec Interpret <refname> as a reference name pattern for a refspec
(as used with remote repositories). If this option is (as used with remote repositories). If this option is
enabled, <refname> is allowed to contain a single `{asterisk}` enabled, <refname> is allowed to contain a single `*`
in place of a one full pathname component (e.g., in place of a one full pathname component (e.g.,
`foo/{asterisk}/bar` but not `foo/bar{asterisk}`). `foo/*/bar` but not `foo/bar*`).
--normalize:: --normalize::
Normalize 'refname' by removing any leading slash (`/`) Normalize 'refname' by removing any leading slash (`/`)
......
...@@ -184,7 +184,7 @@ the conflicted merge in the specified paths. ...@@ -184,7 +184,7 @@ the conflicted merge in the specified paths.
+ +
This means that you can use `git checkout -p` to selectively discard This means that you can use `git checkout -p` to selectively discard
edits from your current working tree. See the ``Interactive Mode'' edits from your current working tree. See the ``Interactive Mode''
section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
<branch>:: <branch>::
Branch to checkout; if it refers to a branch (i.e., a name that, Branch to checkout; if it refers to a branch (i.e., a name that,
...@@ -193,11 +193,11 @@ section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. ...@@ -193,11 +193,11 @@ section of linkgit:git-add[1] to learn how to operate the `\--patch` mode.
commit, your HEAD becomes "detached" and you are no longer on commit, your HEAD becomes "detached" and you are no longer on
any branch (see below for details). any branch (see below for details).
+ +
As a special case, the `"@\{-N\}"` syntax for the N-th last branch As a special case, the `"@{-N}"` syntax for the N-th last branch
checks out the branch (instead of detaching). You may also specify checks out the branch (instead of detaching). You may also specify
`-` which is synonymous with `"@\{-1\}"`. `-` 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 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`. leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
......
...@@ -130,7 +130,7 @@ EXAMPLES ...@@ -130,7 +130,7 @@ EXAMPLES
Apply the changes introduced by all commits that are ancestors Apply the changes introduced by all commits that are ancestors
of master but not of HEAD to produce new commits. of master but not of HEAD to produce new commits.
`git cherry-pick master{tilde}4 master{tilde}2`:: `git cherry-pick master~4 master~2`::
Apply the changes introduced by the fifth and third last Apply the changes introduced by the fifth and third last
commits pointed to by master and create 2 new commits with commits pointed to by master and create 2 new commits with
...@@ -151,7 +151,7 @@ EXAMPLES ...@@ -151,7 +151,7 @@ EXAMPLES
are in next but not HEAD to the current branch, creating a new are in next but not HEAD to the current branch, creating a new
commit for each new change. commit for each new change.
`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: `git rev-list --reverse master -- README | git cherry-pick -n --stdin`::
Apply the changes introduced by all commits on the master Apply the changes introduced by all commits on the master
branch that touched README to the working tree and index, branch that touched README to the working tree and index,
......
...@@ -42,7 +42,7 @@ The content to be added can be specified in several ways: ...@@ -42,7 +42,7 @@ The content to be added can be specified in several ways:
5. by using the --interactive or --patch switches with the 'commit' command 5. by using the --interactive or --patch switches with the 'commit' command
to decide one by one which files or hunks should be part of the commit, to decide one by one which files or hunks should be part of the commit,
before finalizing the operation. See the ``Interactive Mode`` section of before finalizing the operation. See the ``Interactive Mode'' section of
linkgit:git-add[1] to learn how to operate these modes. linkgit:git-add[1] to learn how to operate these modes.
The `--dry-run` option can be used to obtain a The `--dry-run` option can be used to obtain a
...@@ -287,7 +287,7 @@ When recording your own work, the contents of modified files in ...@@ -287,7 +287,7 @@ When recording your own work, the contents of modified files in
your working tree are temporarily stored to a staging area your working tree are temporarily stored to a staging area
called the "index" with 'git add'. A file can be called the "index" with 'git add'. A file can be
reverted back, only in the index but not in the working tree, reverted back, only in the index but not in the working tree,
to that of the last commit with `git reset HEAD \-- <file>`, to that of the last commit with `git reset HEAD -- <file>`,
which effectively reverts 'git add' and prevents the changes to which effectively reverts 'git add' and prevents the changes to
this file from participating in the next commit. After building this file from participating in the next commit. After building
the state to be committed incrementally with these commands, the state to be committed incrementally with these commands,
......
...@@ -252,7 +252,7 @@ Configuring database backend ...@@ -252,7 +252,7 @@ Configuring database backend
'git-cvsserver' uses the Perl DBI module. Please also read 'git-cvsserver' uses the Perl DBI module. Please also read
its documentation if changing these variables, especially its documentation if changing these variables, especially
about `DBI\->connect()`. about `DBI->connect()`.
gitcvs.dbname:: gitcvs.dbname::
Database name. The exact meaning depends on the Database name. The exact meaning depends on the
......
...@@ -104,7 +104,7 @@ marks the same across runs. ...@@ -104,7 +104,7 @@ marks the same across runs.
[<git-rev-list-args>...]:: [<git-rev-list-args>...]::
A list of arguments, acceptable to 'git rev-parse' and A list of arguments, acceptable to 'git rev-parse' and
'git rev-list', that specifies the specific objects and references 'git rev-list', that specifies the specific objects and references
to export. For example, `master{tilde}10..master` causes the to export. For example, `master~10..master` causes the
current master reference to be exported along with all objects current master reference to be exported along with all objects
added since its 10th ancestor commit. added since its 10th ancestor commit.
......
...@@ -478,9 +478,9 @@ current branch value should be written as: ...@@ -478,9 +478,9 @@ current branch value should be written as:
---- ----
from refs/heads/branch^0 from refs/heads/branch^0
---- ----
The `{caret}0` suffix is necessary as fast-import does not permit a branch to The `^0` suffix is necessary as fast-import does not permit a branch to
start from itself, and the branch is created in memory before the start from itself, and the branch is created in memory before the
`from` command is even read from the input. Adding `{caret}0` will force `from` command is even read from the input. Adding `^0` will force
fast-import to resolve the commit through Git's revision parsing library, fast-import to resolve the commit through Git's revision parsing library,
rather than its internal branch table, thereby loading in the rather than its internal branch table, thereby loading in the
existing value of the branch. existing value of the branch.
...@@ -975,7 +975,7 @@ Reading from a named tree:: ...@@ -975,7 +975,7 @@ Reading from a named tree::
See `filemodify` above for a detailed description of `<path>`. See `filemodify` above for a detailed description of `<path>`.
Output uses the same format as `git ls-tree <tree> {litdd} <path>`: Output uses the same format as `git ls-tree <tree> -- <path>`:
==== ====
<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF
......
...@@ -96,8 +96,8 @@ OPTIONS ...@@ -96,8 +96,8 @@ OPTIONS
--index-filter <command>:: --index-filter <command>::
This is the filter for rewriting the index. It is similar to the This is the filter for rewriting the index. It is similar to the
tree filter but does not check out the tree, which makes it much tree filter but does not check out the tree, which makes it much
faster. Frequently used with `git rm \--cached faster. Frequently used with `git rm --cached
\--ignore-unmatch ...`, see EXAMPLES below. For hairy --ignore-unmatch ...`, see EXAMPLES below. For hairy
cases, see linkgit:git-update-index[1]. cases, see linkgit:git-update-index[1].
--parent-filter <command>:: --parent-filter <command>::
...@@ -222,11 +222,11 @@ However, if the file is absent from the tree of some commit, ...@@ -222,11 +222,11 @@ However, if the file is absent from the tree of some commit,
a simple `rm filename` will fail for that tree and commit. a simple `rm filename` will fail for that tree and commit.
Thus you may instead want to use `rm -f filename` as the script. Thus you may instead want to use `rm -f filename` as the script.
Using `\--index-filter` with 'git rm' yields a significantly faster Using `--index-filter` with 'git rm' yields a significantly faster
version. Like with using `rm filename`, `git rm --cached filename` version. Like with using `rm filename`, `git rm --cached filename`
will fail if the file is absent from the tree of a commit. If you will fail if the file is absent from the tree of a commit. If you
want to "completely forget" a file, it does not matter when it entered want to "completely forget" a file, it does not matter when it entered
history, so we also add `\--ignore-unmatch`: history, so we also add `--ignore-unmatch`:
-------------------------------------------------------------------------- --------------------------------------------------------------------------
git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
...@@ -242,8 +242,8 @@ git filter-branch --subdirectory-filter foodir -- --all ...@@ -242,8 +242,8 @@ git filter-branch --subdirectory-filter foodir -- --all
------------------------------------------------------- -------------------------------------------------------
Thus you can, e.g., turn a library subdirectory into a repository of Thus you can, e.g., turn a library subdirectory into a repository of
its own. Note the `\--` that separates 'filter-branch' options from its own. Note the `--` that separates 'filter-branch' options from
revision options, and the `\--all` to rewrite all branches and tags. revision options, and the `--all` to rewrite all branches and tags.
To set a commit (which typically is at the tip of another To set a commit (which typically is at the tip of another
history) to be the parent of the current initial commit, in history) to be the parent of the current initial commit, in
...@@ -371,23 +371,23 @@ Checklist for Shrinking a Repository ...@@ -371,23 +371,23 @@ Checklist for Shrinking a Repository
------------------------------------ ------------------------------------
git-filter-branch is often used to get rid of a subset of files, git-filter-branch is often used to get rid of a subset of files,
usually with some combination of `\--index-filter` and usually with some combination of `--index-filter` and
`\--subdirectory-filter`. People expect the resulting repository to `--subdirectory-filter`. People expect the resulting repository to
be smaller than the original, but you need a few more steps to be smaller than the original, but you need a few more steps to
actually make it smaller, because git tries hard not to lose your actually make it smaller, because git tries hard not to lose your
objects until you tell it to. First make sure that: objects until you tell it to. First make sure that:
* You really removed all variants of a filename, if a blob was moved * You really removed all variants of a filename, if a blob was moved
over its lifetime. `git log \--name-only \--follow \--all \-- over its lifetime. `git log --name-only --follow --all -- filename`
filename` can help you find renames. can help you find renames.
* You really filtered all refs: use `\--tag-name-filter cat \-- * You really filtered all refs: use `--tag-name-filter cat -- --all`
\--all` when calling git-filter-branch. when calling git-filter-branch.
Then there are two ways to get a smaller repository. A safer way is Then there are two ways to get a smaller repository. A safer way is
to clone, that keeps your original intact. to clone, that keeps your original intact.
* Clone it with `git clone +++file:///path/to/repo+++`. The clone * Clone it with `git clone file:///path/to/repo`. The clone
will not have the removed objects. See linkgit:git-clone[1]. (Note will not have the removed objects. See linkgit:git-clone[1]. (Note
that cloning with a plain path just hardlinks everything!) that cloning with a plain path just hardlinks everything!)
...@@ -397,14 +397,14 @@ approach, so *make a backup* or go back to cloning it. You have been ...@@ -397,14 +397,14 @@ approach, so *make a backup* or go back to cloning it. You have been
warned. warned.
* Remove the original refs backed up by git-filter-branch: say `git * Remove the original refs backed up by git-filter-branch: say `git
for-each-ref \--format="%(refname)" refs/original/ | xargs -n 1 git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git
update-ref -d`. update-ref -d`.
* Expire all reflogs with `git reflog expire \--expire=now \--all`. * Expire all reflogs with `git reflog expire --expire=now --all`.
* Garbage collect all unreferenced objects with `git gc \--prune=now` * Garbage collect all unreferenced objects with `git gc --prune=now`
(or if your git-gc is not new enough to support arguments to (or if your git-gc is not new enough to support arguments to
`\--prune`, use `git repack -ad; git prune` instead). `--prune`, use `git repack -ad; git prune` instead).
GIT GIT
--- ---
......
...@@ -45,7 +45,7 @@ There are two ways to specify which commits to operate on. ...@@ -45,7 +45,7 @@ There are two ways to specify which commits to operate on.
The first rule takes precedence in the case of a single <commit>. To The first rule takes precedence in the case of a single <commit>. To
apply the second rule, i.e., format everything since the beginning of apply the second rule, i.e., format everything since the beginning of
history up until <commit>, use the '\--root' option: `git format-patch history up until <commit>, use the '\--root' option: `git format-patch
\--root <commit>`. If you want to format only <commit> itself, you --root <commit>`. If you want to format only <commit> itself, you
can do this with `git format-patch -1 <commit>`. can do this with `git format-patch -1 <commit>`.
By default, each output file is numbered sequentially from 1, and uses the By default, each output file is numbered sequentially from 1, and uses the
...@@ -134,7 +134,7 @@ include::diff-options.txt[] ...@@ -134,7 +134,7 @@ include::diff-options.txt[]
The optional <style> argument can be either `shallow` or `deep`. The optional <style> argument can be either `shallow` or `deep`.
'shallow' threading makes every mail a reply to the head of the 'shallow' threading makes every mail a reply to the head of the
series, where the head is chosen from the cover letter, the series, where the head is chosen from the cover letter, the
`\--in-reply-to`, and the first patch mail, in this order. 'deep' `--in-reply-to`, and the first patch mail, in this order. 'deep'
threading makes every mail a reply to the previous one. threading makes every mail a reply to the previous one.
+ +
The default is `--no-thread`, unless the 'format.thread' configuration The default is `--no-thread`, unless the 'format.thread' configuration
......
...@@ -84,7 +84,7 @@ The optional configuration variable 'gc.reflogExpireUnreachable' ...@@ -84,7 +84,7 @@ The optional configuration variable 'gc.reflogExpireUnreachable'
can be set to indicate how long historical reflog entries which can be set to indicate how long historical reflog entries which
are not part of the current branch should remain available in are not part of the current branch should remain available in
this repository. These types of entries are generally created as this repository. These types of entries are generally created as
a result of using `git commit \--amend` or `git rebase` and are the a result of using `git commit --amend` or `git rebase` and are the
commits prior to the amend or rebase occurring. Since these changes commits prior to the amend or rebase occurring. Since these changes
are not part of the current project most users will want to expire are not part of the current project most users will want to expire
them sooner. This option defaults to '30 days'. them sooner. This option defaults to '30 days'.
......
...@@ -247,11 +247,11 @@ OPTIONS ...@@ -247,11 +247,11 @@ OPTIONS
Examples Examples
-------- --------
`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`:: `git grep 'time_t' -- '*.[ch]'`::
Looks for `time_t` in all tracked .c and .h files in the working Looks for `time_t` in all tracked .c and .h files in the working
directory and its subdirectories. directory and its subdirectories.
`git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`:: `git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)`::
Looks for a line that has `#define` and either `MAX_PATH` or Looks for a line that has `#define` and either `MAX_PATH` or
`PATH_MAX`. `PATH_MAX`.
......
...@@ -100,7 +100,7 @@ Examples ...@@ -100,7 +100,7 @@ Examples
Show all commits since version 'v2.6.12' that changed any file Show all commits since version 'v2.6.12' that changed any file
in the include/scsi or drivers/scsi subdirectories in the include/scsi or drivers/scsi subdirectories
`git log --since="2 weeks ago" \-- gitk`:: `git log --since="2 weeks ago" -- gitk`::
Show the changes during the last two weeks to the file 'gitk'. Show the changes during the last two weeks to the file 'gitk'.
The "--" is necessary to avoid confusion with the *branch* named The "--" is necessary to avoid confusion with the *branch* named
......
...@@ -70,7 +70,7 @@ copy:: ...@@ -70,7 +70,7 @@ copy::
second object). This subcommand is equivalent to: second object). This subcommand is equivalent to:
`git notes add [-f] -C $(git notes list <from-object>) <to-object>` `git notes add [-f] -C $(git notes list <from-object>) <to-object>`
+ +
In `\--stdin` mode, take lines in the format In `--stdin` mode, take lines in the format
+ +
---------- ----------
<from-object> SP <to-object> [ SP <rest> ] LF <from-object> SP <to-object> [ SP <rest> ] LF
......
...@@ -32,7 +32,7 @@ Subsequent updates to branches always create new files under ...@@ -32,7 +32,7 @@ Subsequent updates to branches always create new files under
A recommended practice to deal with a repository with too many A recommended practice to deal with a repository with too many
refs is to pack its refs with `--all --prune` once, and refs is to pack its refs with `--all --prune` once, and
occasionally run `git pack-refs \--prune`. Tags are by occasionally run `git pack-refs --prune`. Tags are by
definition stationary and are not expected to change. Branch definition stationary and are not expected to change. Branch
heads will be packed with the initial `pack-refs --all`, but heads will be packed with the initial `pack-refs --all`, but
only the currently active branch heads will become unpacked, only the currently active branch heads will become unpacked,
......
...@@ -110,7 +110,7 @@ include::merge-options.txt[] ...@@ -110,7 +110,7 @@ include::merge-options.txt[]
+ +
See `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in See `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in
linkgit:git-config[1] if you want to make `git pull` always use linkgit:git-config[1] if you want to make `git pull` always use
`{litdd}rebase` instead of merging. `--rebase` instead of merging.
+ +
[NOTE] [NOTE]
This is a potentially _dangerous_ mode of operation. This is a potentially _dangerous_ mode of operation.
......
...@@ -34,7 +34,7 @@ OPTIONS[[OPTIONS]] ...@@ -34,7 +34,7 @@ OPTIONS[[OPTIONS]]
<refspec>...:: <refspec>...::
The format of a <refspec> parameter is an optional plus The format of a <refspec> parameter is an optional plus
`{plus}`, followed by the source ref <src>, followed `+`, followed by the source ref <src>, followed
by a colon `:`, followed by the destination ref <dst>. by a colon `:`, followed by the destination ref <dst>.
It is used to specify with what <src> object the <dst> ref It is used to specify with what <src> object the <dst> ref
in the remote repository is to be updated. in the remote repository is to be updated.
...@@ -50,7 +50,7 @@ updated. ...@@ -50,7 +50,7 @@ updated.
+ +
The object referenced by <src> is used to update the <dst> reference