# Confusing documentation for git apply -p 3 messages from 2018-04-27 to 2018-05-11. Participants: kelly elton, Jeff King, Junio C Hamano. Thread: https://gitlist.dev/t/48371 ## kelly elton, 2018-04-27 17:40 Subject: Confusing documentation for git apply -p Message-ID: URL: https://gitlist.dev/e/CALVfKe_em046aO9QUqJ0TXcLh6Oe7ydYQKr9Zwvheq8RV4%3D43g%40mail.gmail.com ``` https://git-scm.com/docs/git-apply#git-apply--pltngt > -p > Remove 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 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 - 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, 2018-05-10 14:29 Subject: [PATCH] apply: clarify "-p" documentation Message-ID: <20180510142924.GB25617@sigill.intra.peff.net> URL: https://gitlist.dev/e/20180510142924.GB25617%40sigill.intra.peff.net In-Reply-To: ``` On Fri, Apr 27, 2018 at 12:40:05PM -0500, kelly elton wrote: > > -p > > Remove 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 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 Signed-off-by: Jeff King --- 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:: - Remove leading slashes from traditional diff paths. The - default is 1. + Remove 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:: Ensure at least lines of surrounding context match before -- 2.17.0.984.g9b00a423a4 ``` ## Junio C Hamano, 2018-05-11 03:34 Subject: Re: [PATCH] apply: clarify "-p" documentation Message-ID: URL: https://gitlist.dev/e/xmqqin7uhnma.fsf%40gitster-ct.c.googlers.com In-Reply-To: <20180510142924.GB25617@sigill.intra.peff.net> ``` Jeff King 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 > Signed-off-by: Jeff King > --- > 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:: > - Remove leading slashes from traditional diff paths. The > - default is 1. > + Remove 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:: > Ensure at least lines of surrounding context match before ```