threads / discuss / 48371

Confusing documentation for git apply -p<n>

Subject: Confusing documentation for git apply -p<n>

## tl;dr

3 messages between Apr 27, 2018 and May 11, 2018.

replies: 2people: 3as markdown or json

kelly elton· Apr 27, 2018, 17:40 UTC · lore

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

Jeff King· May 10, 2018, 14:29 UTC · re: kelly elton · lore

[PATCH] apply: clarify "-p" documentation

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

Show 18 quoted lines

> >  -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

Junio C Hamano· May 11, 2018, 03:34 UTC · re: Jeff King · lore

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

Jeff King <peff@peff.net> writes:

Show 28 quoted lines

> 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