git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
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


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