Re: [PATCH v1 1/2] reset: don't compute unstaged changes after reset when --quiet

From: Eric Sunshine <sunshine@sunshineco.com>
To: Ben Peart <peartben@gmail.com>
Cc: Git List <git@vger.kernel.org>,
	Junio C Hamano <gitster@pobox.com>,
	Ben Peart <benpeart@microsoft.com>
Subject: Re: [PATCH v1 1/2] reset: don't compute unstaged changes after reset when --quiet
Date: Wed, 17 Oct 2018 14:14:32 -0400	[thread overview]
Message-ID: <CAPig+cSiE-M9QMch4WE7y4cib1FBUNiaR2pGGtbDuqiz6juhaw@mail.gmail.com> (raw)
In-Reply-To: <20181017164021.15204-2-peartben@gmail.com>

On Wed, Oct 17, 2018 at 12:40 PM Ben Peart <peartben@gmail.com> wrote:
> When git reset is run with the --quiet flag, don't bother finding any
> additional unstaged changes as they won't be output anyway.  This speeds up
> the git reset command by avoiding having to lstat() every file looking for
> changes that aren't going to be reported anyway.
>
> Signed-off-by: Ben Peart <benpeart@microsoft.com>
> ---
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> @@ -95,7 +95,9 @@ OPTIONS
>  --quiet::
> -       Be quiet, only report errors.
> +       Be quiet, only report errors.  Can optimize the performance of reset
> +       by avoiding scaning all files in the repo looking for additional
> +       unstaged changes.

s/scaning/scanning/

However, I'm not convinced that this should be documented here or at
least in this fashion. When I read this new documentation before
reading the commit message, I was baffled by what it was trying to say
since --quiet'ness is a superficial quality, not an optimizer. My
knee-jerk reaction is that it doesn't belong in end-user documentation
at all since it's an implementation detail, however, I can see that
such knowledge could be handy for people in situations which would be
helped by this. That said, if you do document it, this doesn't feel
like the correct place to do so; it should be in a "Discussion"
section or something. (Who would expect to find --quiet documentation
talking about optimizations? Likely, nobody.)