{"thread":{"id":"48371","subject":"Confusing documentation for git apply -p","startedAt":"2018-04-27T17:40:50Z","lastAt":"2018-05-11T03:34:32Z","messageCount":3,"participants":["kelly elton","Jeff King","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"345968","messageId":"CALVfKe_em046aO9QUqJ0TXcLh6Oe7ydYQKr9Zwvheq8RV4=43g@mail.gmail.com","threadId":"48371","inReplyTo":null,"subject":"Confusing documentation for git apply -p","fromName":"kelly elton","fromEmail":"its.the.doc@gmail.com","sentAt":"2018-04-27T17:40:05Z","receivedAt":"2018-04-27T17:40:50Z","isPatch":false,"sender":{"key":"its.the.doc@gmail.com","avatar":null},"body":"https://git-scm.com/docs/git-apply#git-apply--pltngt\n\n> -p\n> Remove leading slashes from traditional diff paths. The default is 1.\n\nThis suggests to me the following outcomes:\n1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n2) home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n3) /home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n4) /home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n5) //home/user/repos/myrepo with -p1 becomes /home/user/repos/myrepo\n6) //home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n\n`Remove leading slashes`...That's not really what's happening.\n\nWhat seems to actually happen is that it is removing directories from the path:\n1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n2) home/user/repos/myrepo with -p2 becomes user/repos/myrepo\n\nThis argument seems to be removing folders from the path, not slashes.\n\nI'm sure it's doing both removing slashes and folders, but at\ndifferent times, which makes it even more confusing to anyone trying\nto wrap their head around it.\n\n-p1= /home/a -> home/a\n-p1= home/a -> home/a ?? Does this happen, or does it actually remove `home`???\n-p2=/home/a -> home/a OR a ??? I have no idea after reading the docs\nand seeing different behavior. I literally have to experiment with it\nto know what it does in each scenario.\n-p2=home/a -> a ?? folder and slash removed.\n\nAll of this doesn't have to be so complicated, it's just being\nexpressed in a complicated way.\n\nBreak this out into two separate functions maybe, or update the\ndocumentation so it's clearer how this behaves.\n\n> -p - number of folders in path to remove from the beginning of the path.\n\nNot great, but clearer than what's there.\n\n\nThanks,\nKelly Elton\nhttp://www.kellyelton.com\n"},{"id":"347243","messageId":"20180510142924.GB25617@sigill.intra.peff.net","threadId":"48371","inReplyTo":"CALVfKe_em046aO9QUqJ0TXcLh6Oe7ydYQKr9Zwvheq8RV4=43g@mail.gmail.com","subject":"[PATCH] apply: clarify \"-p\" documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-05-10T14:29:24Z","receivedAt":"2018-05-10T14:29:28Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Apr 27, 2018 at 12:40:05PM -0500, kelly elton wrote:\n\n> > -p\n> > Remove leading slashes from traditional diff paths. The default is 1.\n> \n> This suggests to me the following outcomes:\n> 1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n> 2) home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n> 3) /home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n> 4) /home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n> 5) //home/user/repos/myrepo with -p1 becomes /home/user/repos/myrepo\n> 6) //home/user/repos/myrepo with -p2 becomes home/user/repos/myrepo\n> \n> `Remove leading slashes`...That's not really what's happening.\n> \n> What seems to actually happen is that it is removing directories from the path:\n> 1) home/user/repos/myrepo with -p1 becomes home/user/repos/myrepo\n> 2) home/user/repos/myrepo with -p2 becomes user/repos/myrepo\n> \n> This argument seems to be removing folders from the path, not slashes.\n\nYes. I agree the current documentation is quite misleading.\n\nHow about this?\n\n-- >8 --\nSubject: [PATCH] apply: clarify \"-p\" documentation\n\nWe're not really removing slashes, but slash-separated path\ncomponents. Let's make that more clear.\n\nReported-by: kelly elton \nSigned-off-by: Jeff King \n---\n Documentation/git-apply.txt | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 4ebc3d3271..c993fbf714 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -113,8 +113,10 @@ explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n -p::\n-\tRemove leading slashes from traditional diff paths. The\n-\tdefault is 1.\n+\tRemove leading path components (separated by slashes) from\n+\ttraditional diff paths. E.g., with `-p2`, a patch against\n+\t`a/dir/file` will be applied directly to `file`. The default is\n+\t1.\n \n -C::\n \tEnsure at least lines of surrounding context match before\n-- \n2.17.0.984.g9b00a423a4\n\n"},{"id":"347331","messageId":"xmqqin7uhnma.fsf@gitster-ct.c.googlers.com","threadId":"48371","inReplyTo":"20180510142924.GB25617@sigill.intra.peff.net","subject":"Re: [PATCH] apply: clarify \"-p\" documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-05-11T03:34:05Z","receivedAt":"2018-05-11T03:34:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> How about this?\n>\n> -- >8 --\n> Subject: [PATCH] apply: clarify \"-p\" documentation\n>\n> We're not really removing slashes, but slash-separated path\n> components. Let's make that more clear.\n>\n> Reported-by: kelly elton \n> Signed-off-by: Jeff King \n> ---\n> Documentation/git-apply.txt | 6 ++++--\n> 1 file changed, 4 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\n> index 4ebc3d3271..c993fbf714 100644\n> --- a/Documentation/git-apply.txt\n> +++ b/Documentation/git-apply.txt\n> @@ -113,8 +113,10 @@ explained for the configuration variable `core.quotePath` (see\n> linkgit:git-config[1]).\n> \n> -p::\n> -\tRemove leading slashes from traditional diff paths. The\n> -\tdefault is 1.\n> +\tRemove leading path components (separated by slashes) from\n> +\ttraditional diff paths. E.g., with `-p2`, a patch against\n> +\t`a/dir/file` will be applied directly to `file`. The default is\n> +\t1.\n\nThanks for an obvious improvement. Will queue.\n\n> \n> -C::\n> \tEnsure at least lines of surrounding context match before\n"}]}