Steven Rostedt [off-list ref] writes:
quoted
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".
quoted
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?
On Tue, 20 Aug 2013 12:45:03 -0700
Junio C Hamano [off-list ref] wrote:
Steven Rostedt [off-list ref] writes:
quoted
quoted
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".
Patch is used by much more than just the kernel folks ;-) I've been
using patch much longer than I've been doing kernel development.
quoted
quoted
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?
Looks good to me. Paul, what do you think?
Thanks,
-- Steve
On 13-08-20 03:54 PM, Steven Rostedt wrote:
On Tue, 20 Aug 2013 12:45:03 -0700
Junio C Hamano [off-list ref] wrote:
quoted
Steven Rostedt [off-list ref] writes:
quoted
quoted
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".
Patch is used by much more than just the kernel folks ;-) I've been
using patch much longer than I've been doing kernel development.
quoted
quoted
quoted
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?
Looks good to me. Paul, what do you think?
Yep, I'll write something up tomorrow which loosely matches the above.
Thanks,
Paul.
--
Thanks,
-- Steve