[1/2] diff, log doc: say "patch text" instead of "patches"
diff mbox series

Message ID fac55175-dc1e-addf-194b-97aaf6a33e3b@kdbg.org
State New
Headers show
Series
  • [1/2] diff, log doc: say "patch text" instead of "patches"
Related show

Commit Message

Johannes Sixt Sept. 15, 2019, 4:55 p.m. UTC
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.

Mention porcelain commands before plumbing commands because I guess that
the paragraph is read more frequently in their context.

Signed-off-by: Johannes Sixt <j6t@kdbg.org>
---
 I do not have the toolchain to check that a correct result is produced.

 Documentation/diff-generate-patch.txt | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

Comments

Martin Ågren Sept. 16, 2019, 5:19 p.m. UTC | #1
On Sun, 15 Sep 2019 at 21:26, Johannes Sixt <j6t@kdbg.org> wrote:
>  I do not have the toolchain to check that a correct result is produced.

But I do. I've tested this patch and 2/2 with AsciiDoc 8.6.10 and
Asciidoctor 1.5.5, as well as with Asciidoctor 2.0.10 (on top of brian's
recent patch so that it builds to begin with). They all render this
nicely.

Both of these patches seem like good changes to me.

Martin
Junio C Hamano Sept. 16, 2019, 7:58 p.m. UTC | #2
Martin Ågren <martin.agren@gmail.com> writes:

> On Sun, 15 Sep 2019 at 21:26, Johannes Sixt <j6t@kdbg.org> wrote:
>>  I do not have the toolchain to check that a correct result is produced.
>
> But I do. I've tested this patch and 2/2 with AsciiDoc 8.6.10 and
> Asciidoctor 1.5.5, as well as with Asciidoctor 2.0.10 (on top of brian's
> recent patch so that it builds to begin with). They all render this
> nicely.
>
> Both of these patches seem like good changes to me.

Thanks, both.  I am neutral between "patch" and "patch text", but if
the latter is more easily understood by readers, that would be
great.  "patch *file*" certainly does sound misleading.

I wonder if the result becomes even clearer if we dropped "instead
of the usual output".  It is a given that presence of an option
would change the behaviour, so "instead of the usual" does not add
any value in the context of the explanation we are giving.

Also I question the value of the "running git diff without --raw
option" sentence; "diff --stat" is also a way to suppress the patch
text and see only the overview; I know it is not a new problem this
patch introduces, but the objective of this patch is clarify about
the generation of output in patch format, so...

Patch
diff mbox series

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index f10ca410ad..c6bbb2ac22 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -1,11 +1,12 @@ 
-Generating patches with -p
---------------------------
-
-When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
-with a `-p` option, "git diff" without the `--raw` option, or
-"git log" with the "-p" option, they
-do not produce the output described above; instead they produce a
-patch file.  You can customize the creation of such patches via the
+Generating patch text with -p
+-----------------------------
+
+Running
+linkgit:git-diff[1] without the `--raw` option,
+or linkgit:git-log[1], linkgit:git-diff-index[1], linkgit:git-diff-tree[1],
+or linkgit:git-diff-files[1] with the `-p` option
+produces patch text instead of the usual output.
+You can customize the creation of patch text via the
 `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables.
 
 What the -p option produces is slightly different from the traditional