From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Jeff King <peff@peff.net>
Cc: Taylor Blau <me@ttaylorr.com>, Junio C Hamano <gitster@pobox.com>,
git@vger.kernel.org, Kyle Meyer <kyle@kyleam.com>,
Eric Sunshine <sunshine@sunshineco.com>
Subject: Re: [PATCH v2] rev-list --disk-usage
Date: Thu, 11 Feb 2021 13:04:26 +0100 [thread overview]
Message-ID: <875z2ydd4l.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <YCUOSmnsJ4LLPFgK@coredump.intra.peff.net>
On Thu, Feb 11 2021, Jeff King wrote:
> On Wed, Feb 10, 2021 at 06:15:16PM -0500, Taylor Blau wrote:
>
>> > > I kind of feel sad to have a nice write-up like this only in the
>> > > list archive. Is there a section in our documentation set to keep
>> > > collection of such a real-life use cases? Perhaps the examples
>> > > section of manpages is the closest thing, but it looks a bit too
>> > > narrowly scoped for the example section of "rev-list" manpage.
>> >
>> > Agreed on both counts. If this gets put into a release, I suspect Taylor
>> > would cover it in a release blog post. That is not quite the same thing
>> > as having it in the documentation, but it may provide more search engine
>> > boost than the list archive. I dunno.
>>
>> Yeah, this is the perfect sort of thing for those blog posts.
>>
>> But it makes sense to include some of these examples in our own
>> documentation here, too. git-rev-list(1) doesn't have an EXAMPLES
>> section, but maybe it should.
>
> I think this is the "narrowly scoped" bit from Junio's response above.
> It would be a bit weird to have an examples section for rev-list that
> only mentions this rather obscure feature.
I don't think the lack of an EXAMPLES section or the relative obscurity
of the switch should preclude us from adding useful documentation.
Yes it would feel a bit out of place, but we can always have a
sub-section of EXAMPLES, and we've got to start somewhere.
In this case I don't see why it couldn't be added to OPTIONS, we've got
some very long discussion there already, and as long as there's a clear
separation in prose from an initial brief discussion of the switch and
further prose it won't be confusing for readers, they can just page past
the details.
next prev parent reply other threads:[~2021-02-11 12:08 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-27 22:11 [PATCH 0/2] rev-list --disk-usage Jeff King
2021-01-27 22:12 ` [PATCH 1/2] t: add --no-tag option to test_commit Jeff King
2021-01-27 22:48 ` Taylor Blau
2021-01-27 22:17 ` [PATCH 2/2] rev-list: add --disk-usage option for calculating disk usage Jeff King
2021-01-27 22:57 ` Taylor Blau
2021-01-27 23:34 ` Jeff King
2021-01-27 23:01 ` Kyle Meyer
2021-01-27 23:36 ` Jeff King
2021-01-27 23:07 ` Eric Sunshine
2021-01-27 23:39 ` Jeff King
2021-01-27 22:46 ` [PATCH 0/2] rev-list --disk-usage Taylor Blau
2021-02-09 10:52 ` [PATCH v2] " Jeff King
2021-02-09 10:52 ` [PATCH v2 1/2] t: add --no-tag option to test_commit Jeff King
2021-02-09 10:53 ` [PATCH v2 2/2] rev-list: add --disk-usage option for calculating disk usage Jeff King
2021-02-09 11:09 ` [PATCH v2] rev-list --disk-usage Jeff King
2021-02-09 21:14 ` Junio C Hamano
2021-02-10 9:38 ` Jeff King
2021-02-10 0:44 ` Junio C Hamano
2021-02-10 1:49 ` Taylor Blau
2021-02-10 10:01 ` Jeff King
2021-02-10 16:31 ` Junio C Hamano
2021-02-10 20:38 ` Jeff King
2021-02-10 23:15 ` Taylor Blau
2021-02-11 11:00 ` Jeff King
2021-02-11 12:04 ` Ævar Arnfjörð Bjarmason [this message]
2021-02-11 17:57 ` Junio C Hamano
2021-02-17 23:31 ` [PATCH 0/2] rev-list --disk-usage example docs Jeff King
2021-02-17 23:34 ` [PATCH 1/2] docs/rev-list: add an examples section Jeff King
2021-02-17 23:35 ` [PATCH 2/2] docs/rev-list: add some examples of --disk-usage Jeff King
2021-02-17 23:44 ` [PATCH 0/2] rev-list --disk-usage example docs Taylor Blau
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=875z2ydd4l.fsf@evledraar.gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=kyle@kyleam.com \
--cc=me@ttaylorr.com \
--cc=peff@peff.net \
--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.
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 NNTP newsgroup(s).