[v3,1/2] range-diff doc: add a section about output stability
diff mbox series

Message ID 20181107122202.1813-2-avarab@gmail.com
State New
Headers show
Series
  • [v3,1/2] range-diff doc: add a section about output stability
Related show

Commit Message

Ævar Arnfjörð Bjarmason Nov. 7, 2018, 12:22 p.m. UTC
The range-diff command is already advertised as porcelain, but let's
make it really clear that the output is completely subject to change,
particularly when it comes to diff options such as --stat. Right now
that option doesn't work, but fixing that is the subject of a later
change.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-range-diff.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Comments

Stephen P. Smith Nov. 7, 2018, 1:10 p.m. UTC | #1
On Wednesday, November 7, 2018 5:22:01 AM MST Ævar Arnfjörð Bjarmason wrote:
> +OUTPUT STABILITY
> +----------------
> +
> +The output of the `range-diff` command is subject to change. It is
> +intended to be human-readable porcelain output, not something that can
> +be used across versions of Git to get a textually stable `range-diff`
> +(as opposed to something like the `--stable` option to
> +linkgit:git-patch-id[1]). There's also no equivalent of
> +linkgit:git-apply[1] for `range-diff`, the output is not intended to
> +be machine-readable.
> +
> +This is particularly true when passing in diff options. Currently some
> +options like `--stat` can as an emergent effect produce output that's

"`--stat` can as an emergent": I read that for times to decided it was correct 
grammar.   Should it be reworded to read better?   Just a nit.

> +quite useless in the context of `range-diff`. Future versions of
> +`range-diff` may learn to interpret such options in a manner specifc
> +to `range-diff` (e.g. for `--stat` summarizing how the diffstat
> +changed).
Martin Ågren Nov. 7, 2018, 7:06 p.m. UTC | #2
On Wed, 7 Nov 2018 at 13:22, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
> +
> +This is particularly true when passing in diff options. Currently some
> +options like `--stat` can as an emergent effect produce output that's
> +quite useless in the context of `range-diff`. Future versions of
> +`range-diff` may learn to interpret such options in a manner specifc

s/specifc/specific/

> +to `range-diff` (e.g. for `--stat` summarizing how the diffstat
> +changed).
Junio C Hamano Nov. 7, 2018, 10:52 p.m. UTC | #3
Stephen & Linda Smith <ischis2@cox.net> writes:

>> +This is particularly true when passing in diff options. Currently some
>> +options like `--stat` can as an emergent effect produce output that's
>
> "`--stat` can as an emergent": I read that for times to decided it was correct 
> grammar.   Should it be reworded to read better?   Just a nit.

A pair of comma around "as an ... effect" would make it a bit more
readable.  It also took me four reads before I convinced myself that
the original wants to say "Some options may just do whatever they
happen to do that result in pretty useless output".

>
>> +quite useless in the context of `range-diff`. Future versions of
>> +`range-diff` may learn to interpret such options in a manner specifc
>> +to `range-diff` (e.g. for `--stat` summarizing how the diffstat
>> +changed).

Patch
diff mbox series

diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index f693930fdb..bbd07a9be8 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -78,6 +78,23 @@  between patches", i.e. to compare the author, commit message and diff of
 corresponding old/new commits. There is currently no means to tweak the
 diff options passed to `git log` when generating those patches.
 
+OUTPUT STABILITY
+----------------
+
+The output of the `range-diff` command is subject to change. It is
+intended to be human-readable porcelain output, not something that can
+be used across versions of Git to get a textually stable `range-diff`
+(as opposed to something like the `--stable` option to
+linkgit:git-patch-id[1]). There's also no equivalent of
+linkgit:git-apply[1] for `range-diff`, the output is not intended to
+be machine-readable.
+
+This is particularly true when passing in diff options. Currently some
+options like `--stat` can as an emergent effect produce output that's
+quite useless in the context of `range-diff`. Future versions of
+`range-diff` may learn to interpret such options in a manner specifc
+to `range-diff` (e.g. for `--stat` summarizing how the diffstat
+changed).
 
 CONFIGURATION
 -------------