range-diff doc: add a section about output stability
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Nov 9, 2018 at 10:18 UTC
df569c3f31f4aab5f9fd003029090a321bacd2bd
1 file changed
+17
Documentation/git-range-diff.txt
+17
@@ -78,6 +78,23 @@ between patches", i.e. to compare the author, commit message and diff of
78
corresponding old/new commits. There is currently no means to tweak the
79
diff options passed to `git log` when generating those patches.
80
81
+OUTPUT STABILITY
82
+----------------
83
+
84
+The output of the `range-diff` command is subject to change. It is
85
+intended to be human-readable porcelain output, not something that can
86
+be used across versions of Git to get a textually stable `range-diff`
87
+(as opposed to something like the `--stable` option to
88
+linkgit:git-patch-id[1]). There's also no equivalent of
89
+linkgit:git-apply[1] for `range-diff`, the output is not intended to
90
+be machine-readable.
91
+
92
+This is particularly true when passing in diff options. Currently some
93
+options like `--stat` can, as an emergent effect, produce output
94
+that's quite useless in the context of `range-diff`. Future versions
95
+of `range-diff` may learn to interpret such options in a manner
96
+specific to `range-diff` (e.g. for `--stat` producing human-readable
97
+output which summarizes how the diffstat changed).
98
99
CONFIGURATION
100
-------------