Re: Should "git apply --check" imply verbose?

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 20, 2013, 19:45 UTC
Message-ID: <7v7gfgkuyo.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20130820151554.6afbcb7f@gandalf.local.home>

Steven Rostedt <rostedt@goodmis.org> writes:

Show 6 quoted lines

>> I do not think it is necessarily a good idea to assume that people
>> who are learning "git apply" know how GNU patch works.
>
> Linus told me that "git apply" was basically a replacement for patch.
> Why would you think it would not be a good idea to assume that people
> would not be familiar with how GNU patch works?

The audience of Git these days are far more widely spread than the kernel circle. I am not opposed to _helping_ those who happen to know "patch", but I was against a description that assumes readers know it, i.e. making it a requirement to know "patch" to understand "apply".

Show 9 quoted lines

>> But I do agree that the description of -v, --verbose has a lot of
>> room for improvement.
>> 
>> 	Report progress to stderr. By default, only a message about the
>> 	current patch being applied will be printed. This option will cause
>> 	additional information to be reported.
>> 
>> It is totally unclear what "additional information" is reported at
>> all.

In other words, your enhancement to the documentation could go like:

	... By default, ... With this option, you will additionally
	see such and such and such in the output (this is similar to
	what "patch --dry-run" would give you).  See the EXAMPLES
	section to get a feel of how it looks like.

and I would not be opposed, as long as "such and such and such" are written in such a way that the reader does not have to have a prior experience with GNU patch in order to understand it.

Clear?