From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>,
"Lucas De Marchi" <lucas.demarchi@intel.com>,
"Stefan Beller" <sbeller@google.com>,
"Eric Sunshine" <sunshine@sunshineco.com>,
"Johannes Schindelin" <johannes.schindelin@gmx.de>,
"Stephen & Linda Smith" <ischis2@cox.net>,
"Martin Ågren" <martin.agren@gmail.com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v4 1/3] range-diff doc: add a section about output stability
Date: Fri, 9 Nov 2018 10:18:01 +0000 [thread overview]
Message-ID: <20181109101803.3038-2-avarab@gmail.com> (raw)
In-Reply-To: <20181107122202.1813-3-avarab@gmail.com>
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(+)
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index f693930fdb..8a6ea2c6c5 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
+specific to `range-diff` (e.g. for `--stat` producing human-readable
+output which summarizes how the diffstat changed).
CONFIGURATION
-------------
--
2.19.1.1182.g4ecb1133ce
next prev parent reply other threads:[~2018-11-09 10:18 UTC|newest]
Thread overview: 40+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-05 20:06 [PATCH] range-diff: add a --no-patch option to show a summary Ævar Arnfjörð Bjarmason
2018-11-05 20:26 ` Eric Sunshine
2018-11-05 21:00 ` Ævar Arnfjörð Bjarmason
2018-11-06 10:43 ` Johannes Schindelin
2018-11-06 16:01 ` Ævar Arnfjörð Bjarmason
2018-11-07 10:34 ` Johannes Schindelin
2018-11-07 10:43 ` Johannes Schindelin
2018-11-07 10:55 ` Johannes Schindelin
2018-11-07 11:08 ` Johannes Schindelin
2018-11-07 12:22 ` [PATCH v3 0/2] range-diff: doc + regression fix Ævar Arnfjörð Bjarmason
2018-11-07 12:22 ` [PATCH v3 1/2] range-diff doc: add a section about output stability Ævar Arnfjörð Bjarmason
2018-11-07 13:10 ` Stephen & Linda Smith
2018-11-07 22:52 ` Junio C Hamano
2018-11-07 19:06 ` Martin Ågren
2018-11-07 12:22 ` [PATCH v3 2/2] range-diff: fix regression in passing along diff options Ævar Arnfjörð Bjarmason
2018-11-08 17:08 ` Eric Sunshine
2018-11-08 22:34 ` Ævar Arnfjörð Bjarmason
2018-11-09 6:46 ` Eric Sunshine
2018-11-09 7:36 ` Ævar Arnfjörð Bjarmason
2018-11-09 10:18 ` [PATCH v4 0/3] range-diff fixes Ævar Arnfjörð Bjarmason
2018-11-09 16:32 ` Johannes Schindelin
2018-11-09 10:18 ` Ævar Arnfjörð Bjarmason [this message]
2018-11-09 10:18 ` [PATCH v4 2/3] range-diff: fix regression in passing along diff options Ævar Arnfjörð Bjarmason
2018-11-09 10:18 ` [PATCH v4 3/3] range-diff: make diff option behavior (e.g. --stat) consistent Ævar Arnfjörð Bjarmason
2018-11-09 13:25 ` Stephen & Linda Smith
2018-11-11 8:43 ` Eric Sunshine
2018-11-12 3:17 ` Junio C Hamano
2018-11-12 3:32 ` Junio C Hamano
2018-11-13 18:55 ` [PATCH v5 0/3] range-diff fixes Ævar Arnfjörð Bjarmason
2018-11-14 15:36 ` Johannes Schindelin
2018-11-13 18:55 ` [PATCH v5 1/3] range-diff doc: add a section about output stability Ævar Arnfjörð Bjarmason
2018-11-13 18:55 ` [PATCH v5 2/3] range-diff: fix regression in passing along diff options Ævar Arnfjörð Bjarmason
2018-11-13 18:55 ` [PATCH v5 3/3] range-diff: make diff option behavior (e.g. --stat) consistent Ævar Arnfjörð Bjarmason
2018-11-06 4:16 ` [PATCH] range-diff: add a --no-patch option to show a summary Junio C Hamano
2018-11-06 5:15 ` Eric Sunshine
2018-11-06 5:57 ` Junio C Hamano
2018-11-06 8:36 ` Ævar Arnfjörð Bjarmason
2018-11-06 16:24 ` [PATCH v2] " Ævar Arnfjörð Bjarmason
2018-11-07 0:57 ` Junio C Hamano
2018-11-07 11:11 ` Johannes Schindelin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181109101803.3038-2-avarab@gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=ischis2@cox.net \
--cc=johannes.schindelin@gmx.de \
--cc=lucas.demarchi@intel.com \
--cc=martin.agren@gmail.com \
--cc=sbeller@google.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).