user/sven/git.git/Documentation/diff-generate-patch.txt, branch v2.26.0-rc2

diff, log doc: small grammer, format, and language fixes

2019-09-17T19:14:06Z

- Replace "SHA-1" by "object name", the modern name for hashes. - Correct a few grammar weaknesses. - Do not accidentally format a phrase in teletype font where quotes are intended. Signed-off-by: Johannes Sixt Signed-off-by: Junio C Hamano

diff, log doc: say "patch text" instead of "patches"

2019-09-17T19:13:27Z

diff, log doc: say "patch text" instead of "patches" A poster on Stackoverflow was confused that the documentation of git-log promised to generate "patches" or "patch files" with -p, but there were none to be found. Rewrite the corresponding paragraph to talk about "patch text" to avoid the confusion. Shorten the language to say "X does Y" in place of "X does not Z, but Y". Cross-reference the referred-to commands like the rest of the file does. Enumerate git-show because it includes the description as well. Mention porcelain commands before plumbing commands because I guess that the paragraph is read more frequently in their context. Signed-off-by: Johannes Sixt Acked-by: Martin Ågren Signed-off-by: Junio C Hamano

log,diff-tree: add --combined-all-paths option

2019-02-08T04:15:25Z

The combined diff format for merges will only list one filename, even if rename or copy detection is active. For example, with raw format one might see: ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM describe.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh ::100644 100644 100644 e07d6c5 9042e82 ee91881 RR phooey.c This doesn't let us know what the original name of bar.sh was in the first parent, and doesn't let us know what either of the original names of phooey.c were in either of the parents. In contrast, for non-merge commits, raw format does provide original filenames (and a rename score to boot). In order to also provide original filenames for merge commits, add a --combined-all-paths option (which must be used with either -c or --cc, and is likely only useful with rename or copy detection active) so that we can print tab-separated filenames when renames are involved. This transforms the above output to: ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c desc.c desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM foo.sh bar.sh bar.sh ::100644 100644 100644 e07d6c5 9042e82 ee91881 RR fooey.c fuey.c phooey.c Further, in patch format, this changes the from/to headers so that instead of just having one "from" header, we get one for each parent. For example, instead of having --- a/phooey.c +++ b/phooey.c we would see --- a/fooey.c --- a/fuey.c +++ b/phooey.c Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

Documentation: improve description for core.quotePath

2017-03-02T19:40:51Z

Linking the description for pathname quoting to the configuration variable "core.quotePath" removes inconstistent and incomplete sections while also giving two hints how to deal with it: Either with "-c core.quotePath=false" or with "-z". Signed-off-by: Andreas Heiduk Signed-off-by: Junio C Hamano

doc: typeset long command-line options as literal

2016-06-28T15:36:45Z

Similarly to the previous commit, use backquotes instead of forward-quotes, for long options. This was obtained with: perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt and manual tweak to remove false positive in ascii-art (o'--o'--o' to describe rewritten history). Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano

doc: typeset short command-line options as literal

2016-06-28T15:20:52Z

It was common in our documentation to surround short option names with forward quotes, which renders as italic in HTML. Instead, use backquotes which renders as monospace. This is one more step toward conformance to Documentation/CodingGuidelines. This was obtained with: perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano

doc: more consistency in environment variables format

2016-06-08T19:04:37Z

Wrap with backticks (monospaced font) unwrapped or single-quotes wrapped (italic type) environment variables which are followed by the word "environment". It was obtained with: perl -pi -e "s/\'?(\\\$?[0-9A-Z\_]+)\'?(?= environment ?)/\`\1\`/g" *.txt One of the main purposes is to stick to the CodingGuidelines as possible so that people writting new documentation by mimicking the existing are more likely to have it right (even if they didn't read the CodingGuidelines). Signed-off-by: Tom Russello Signed-off-by: Erwan Mathoniere Signed-off-by: Samuel Groot Signed-off-by: Matthieu Moy Reviewed-by: Matthieu Moy Signed-off-by: Junio C Hamano

doc: fix misrendering due to `single quote'

2015-05-13T05:13:39Z

AsciiDoc misparses some text that contains a `literal` word followed by a fancy `single quote' word, and treats everything from the start of the literal to the end of the quote as a single-quoted phrase. We can work around this by switching the latter to be a literal, as well. In the first case, this is perhaps what was intended anyway, as it makes us consistent with the the earlier literals in the same paragraph. In the second, the output is arguably better, as we will format our commit references as

 blocks.

Signed-off-by: Jeff King 
Signed-off-by: Junio C Hamano



Documentation: fix misuses of "nor"
2014-03-31T22:16:22Z
Signed-off-by: Justin Lebar 
Signed-off-by: Junio C Hamano 


docs: stop using asciidoc no-inline-literal
2012-04-26T20:19:06Z
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