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

From

Ævar Arnfjörð Bjarmason <avarab@gmail.com>

Date

Nov 7, 2018, 12:22 UTC

Message-ID

<20181107122202.1813-2-avarab@gmail.com>

In-Reply-To

<nycvar.QRO.7.76.6.1811071202480.39@tvgsbejvaqbjf.bet>

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

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
 -------------

-- 
2.19.1.930.g4563a0d9d0