| Message ID | 20181107122202.1813-2-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3,1/2] range-diff doc: add a section about output stability | expand |
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).
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).
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).
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 -------------
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(+)