Confusing documentation for git apply -p<n>

Confusing documentation for git apply -p<n>

[kelly elton]

https://git-scm.com/docs/git-apply#git-apply--pltngt

>  -p<n>
> Remove <n> leading slashes from traditional diff paths. The default is 1.

This suggests to me the following outcomes:
1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
2) home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo
3) /home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
4) /home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo
5) //home/user/repos/myrepo with -p1 becomes /home/user/repos/myrepo
6) //home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo

`Remove <n> leading slashes`...That's not really what's happening.

What seems to actually happen is that it is removing directories from the path:
1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
2) home/user/repos/myrepo with -p2 becomes user/repos/myrepo

This argument seems to be removing folders from the path, not slashes.

I'm sure it's doing both removing slashes and folders, but at
different times, which makes it even more confusing to anyone trying
to wrap their head around it.

-p1= /home/a -> home/a
-p1= home/a -> home/a ?? Does this happen, or does it actually remove `home`???
-p2=/home/a -> home/a OR a ??? I have no idea after reading the docs
and seeing different behavior. I literally have to experiment with it
to know what it does in each scenario.
-p2=home/a -> a ?? folder and slash removed.

All of this doesn't have to be so complicated, it's just being
expressed in a complicated way.

Break this out into two separate functions maybe, or update the
documentation so it's clearer how this behaves.

> -p<n> - number of folders in path to remove from the beginning of the path.

Not great, but clearer than what's there.


Thanks,
Kelly Elton
http://www.kellyelton.com

[PATCH] apply: clarify "-p" documentation

[Jeff King]

On Fri, Apr 27, 2018 at 12:40:05PM -0500, kelly elton wrote:

> >  -p<n>
> > Remove <n> leading slashes from traditional diff paths. The default is 1.
> 
> This suggests to me the following outcomes:
> 1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
> 2) home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo
> 3) /home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
> 4) /home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo
> 5) //home/user/repos/myrepo with -p1 becomes /home/user/repos/myrepo
> 6) //home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo
> 
> `Remove <n> leading slashes`...That's not really what's happening.
> 
> What seems to actually happen is that it is removing directories from the path:
> 1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo
> 2) home/user/repos/myrepo with -p2 becomes user/repos/myrepo
> 
> This argument seems to be removing folders from the path, not slashes.

Yes. I agree the current documentation is quite misleading.

How about this?

-- >8 --
Subject: [PATCH] apply: clarify "-p" documentation

We're not really removing slashes, but slash-separated path
components. Let's make that more clear.

Reported-by: kelly elton <its.the.doc@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-apply.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 4ebc3d3271..c993fbf714 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -113,8 +113,10 @@ explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
 -p<n>::
-	Remove <n> leading slashes from traditional diff paths. The
-	default is 1.
+	Remove <n> leading path components (separated by slashes) from
+	traditional diff paths. E.g., with `-p2`, a patch against
+	`a/dir/file` will be applied directly to `file`. The default is
+	1.
 
 -C<n>::
 	Ensure at least <n> lines of surrounding context match before
-- 
2.17.0.984.g9b00a423a4

Re: [PATCH] apply: clarify "-p" documentation

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> How about this?
>
> -- >8 --
> Subject: [PATCH] apply: clarify "-p" documentation
>
> We're not really removing slashes, but slash-separated path
> components. Let's make that more clear.
>
> Reported-by: kelly elton <its.the.doc@gmail.com>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-apply.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
> index 4ebc3d3271..c993fbf714 100644
> --- a/Documentation/git-apply.txt
> +++ b/Documentation/git-apply.txt
> @@ -113,8 +113,10 @@ explained for the configuration variable `core.quotePath` (see
>  linkgit:git-config[1]).
>  
>  -p<n>::
> -	Remove <n> leading slashes from traditional diff paths. The
> -	default is 1.
> +	Remove <n> leading path components (separated by slashes) from
> +	traditional diff paths. E.g., with `-p2`, a patch against
> +	`a/dir/file` will be applied directly to `file`. The default is
> +	1.

Thanks for an obvious improvement.  Will queue.

>  
>  -C<n>::
>  	Ensure at least <n> lines of surrounding context match before