threads / patch / 47576

patchdoc/read-tree: remove obsolete remark

Subject: [PATCH] doc/read-tree: remove obsolete remark

## tl;dr

7 messages between Jan 9, 2018 and Jan 12, 2018. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Andreas G. Schacker· Jan 9, 2018, 15:30 UTC · lore

Earlier versions of `git read-tree` required the `--prefix` option value to end with a slash. This restriction was eventually lifted without a corresponding amendment to the documentation.

Signed-off-by: Andreas G. Schacker <andreas.schacker@gmail.com>
---
 Documentation/git-read-tree.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Show changes to Documentation/git-read-tree.txt +2 −2
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 72bd809fb..f2a07d54d 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -81,12 +81,11 @@ OPTIONS
 * when both sides add a path identically.  The resolution
   is to add that path.
 
---prefix=<prefix>/::
+--prefix=<prefix>::
 	Keep the current index contents, and read the contents
 	of the named tree-ish under the directory at `<prefix>`.
 	The command will refuse to overwrite entries that already
-	existed in the original index file. Note that the `<prefix>/`
-	value must end with a slash.
+	existed in the original index file.
 
 --exclude-per-directory=<gitignore>::
 	When running the command with `-u` and `-m` options, the

-- 
2.15.1
Junio C Hamano· Jan 9, 2018, 19:36 UTC · re: Andreas G. Schacker · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

"Andreas G. Schacker" <andreas.schacker@gmail.com> writes:
Show 6 quoted lines
> Earlier versions of `git read-tree` required the `--prefix` option value
> to end with a slash. This restriction was eventually lifted without a
> corresponding amendment to the documentation.
>
> Signed-off-by: Andreas G. Schacker <andreas.schacker@gmail.com>
> ---

Thanks. "read-tree --prefix=foo- $tree" is allowed these days, indeed. Will queue.

What is curious is that 34110cd4 ("Make 'unpack_trees()' have a separate source and destination index", 2008-03-06) seems to be the one that removed the check, and the removed contents do not seem to have much in common with the stated goal of the commit.

Show 22 quoted lines
>  Documentation/git-read-tree.txt | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> index 72bd809fb..f2a07d54d 100644
> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -81,12 +81,11 @@ OPTIONS
>  * when both sides add a path identically.  The resolution
>    is to add that path.
>  
> ---prefix=<prefix>/::
> +--prefix=<prefix>::
>  	Keep the current index contents, and read the contents
>  	of the named tree-ish under the directory at `<prefix>`.
>  	The command will refuse to overwrite entries that already
> -	existed in the original index file. Note that the `<prefix>/`
> -	value must end with a slash.
> +	existed in the original index file.
>  
>  --exclude-per-directory=<gitignore>::
>  	When running the command with `-u` and `-m` options, the
Jeff King· Jan 11, 2018, 10:49 UTC · re: Andreas G. Schacker · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

On Tue, Jan 09, 2018 at 04:30:34PM +0100, Andreas G. Schacker wrote:
> Earlier versions of `git read-tree` required the `--prefix` option value
> to end with a slash. This restriction was eventually lifted without a
> corresponding amendment to the documentation.
Makes sense.
Show 8 quoted lines
> ---prefix=<prefix>/::
> +--prefix=<prefix>::
>  	Keep the current index contents, and read the contents
>  	of the named tree-ish under the directory at `<prefix>`.
>  	The command will refuse to overwrite entries that already
> -	existed in the original index file. Note that the `<prefix>/`
> -	value must end with a slash.
> +	existed in the original index file.

Is it worth mentioning in the new world order that the slash is not implied? I.e., that you probably do want to say "--prefix=foo/" if you want the subdirectory "foo", but do not want to match "foobar"?

-Peff
Junio C Hamano· Jan 11, 2018, 19:02 UTC · re: Jeff King · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

Jeff King <peff@peff.net> writes:
Show 20 quoted lines
> On Tue, Jan 09, 2018 at 04:30:34PM +0100, Andreas G. Schacker wrote:
>
>> Earlier versions of `git read-tree` required the `--prefix` option value
>> to end with a slash. This restriction was eventually lifted without a
>> corresponding amendment to the documentation.
>
> Makes sense.
>
>> ---prefix=<prefix>/::
>> +--prefix=<prefix>::
>>  	Keep the current index contents, and read the contents
>>  	of the named tree-ish under the directory at `<prefix>`.
>>  	The command will refuse to overwrite entries that already
>> -	existed in the original index file. Note that the `<prefix>/`
>> -	value must end with a slash.
>> +	existed in the original index file.
>
> Is it worth mentioning in the new world order that the slash is not
> implied? I.e., that you probably do want to say "--prefix=foo/" if you
> want the subdirectory "foo", but do not want to match "foobar"?

Doesn't "git read-tree --prefix=previous HEAD^" add paths like "previous/Documentation/Makefile" to the index, i.e. instead of forcing you to have the required slash at the end, we give one for free when it is missing?

Jeff King· Jan 11, 2018, 22:21 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

On Thu, Jan 11, 2018 at 11:02:04AM -0800, Junio C Hamano wrote:
Show 17 quoted lines
> >> ---prefix=<prefix>/::
> >> +--prefix=<prefix>::
> >>  	Keep the current index contents, and read the contents
> >>  	of the named tree-ish under the directory at `<prefix>`.
> >>  	The command will refuse to overwrite entries that already
> >> -	existed in the original index file. Note that the `<prefix>/`
> >> -	value must end with a slash.
> >> +	existed in the original index file.
> >
> > Is it worth mentioning in the new world order that the slash is not
> > implied? I.e., that you probably do want to say "--prefix=foo/" if you
> > want the subdirectory "foo", but do not want to match "foobar"?
> 
> Doesn't "git read-tree --prefix=previous HEAD^" add paths like
> "previous/Documentation/Makefile" to the index, i.e. instead of
> forcing you to have the required slash at the end, we give one for
> free when it is missing?

Yes, I think it does what you'd want with that path. But it would not do what you want by adding "previous-file". Which seems like a gotcha that should be mentioned.

-Peff
Junio C Hamano· Jan 11, 2018, 23:14 UTC · re: Jeff King · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

Jeff King <peff@peff.net> writes:
Show 23 quoted lines
> On Thu, Jan 11, 2018 at 11:02:04AM -0800, Junio C Hamano wrote:
>
>> >> ---prefix=<prefix>/::
>> >> +--prefix=<prefix>::
>> >>  	Keep the current index contents, and read the contents
>> >>  	of the named tree-ish under the directory at `<prefix>`.
>> >>  	The command will refuse to overwrite entries that already
>> >> -	existed in the original index file. Note that the `<prefix>/`
>> >> -	value must end with a slash.
>> >> +	existed in the original index file.
>> >
>> > Is it worth mentioning in the new world order that the slash is not
>> > implied? I.e., that you probably do want to say "--prefix=foo/" if you
>> > want the subdirectory "foo", but do not want to match "foobar"?
>> 
>> Doesn't "git read-tree --prefix=previous HEAD^" add paths like
>> "previous/Documentation/Makefile" to the index, i.e. instead of
>> forcing you to have the required slash at the end, we give one for
>> free when it is missing?
>
> Yes, I think it does what you'd want with that path. But it would not do
> what you want by adding "previous-file". Which seems like a gotcha that
> should be mentioned.
I am a bit puzzled.

Do you mean a user who types "git read-tree --prefix=v1- HEAD^" may be expecting to see that the blob object "HEAD^:Makefile" added at path "v1-Makefile" etc?

Jeff King· Jan 12, 2018, 00:35 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc/read-tree: remove obsolete remark

On Thu, Jan 11, 2018 at 03:14:07PM -0800, Junio C Hamano wrote:
Show 14 quoted lines
> >> Doesn't "git read-tree --prefix=previous HEAD^" add paths like
> >> "previous/Documentation/Makefile" to the index, i.e. instead of
> >> forcing you to have the required slash at the end, we give one for
> >> free when it is missing?
> >
> > Yes, I think it does what you'd want with that path. But it would not do
> > what you want by adding "previous-file". Which seems like a gotcha that
> > should be mentioned.
> 
> I am a bit puzzled.  
> 
> Do you mean a user who types "git read-tree --prefix=v1- HEAD^" may
> be expecting to see that the blob object "HEAD^:Makefile" added at
> path "v1-Makefile" etc?

Sorry, I was somewhat turned around in my example, thinking that we were matching existing entries by prefix here and not putting entries into a new prefix[1].

But yes, your example hits the point that I think is left unsaid: does "--prefix=sub" mean the same thing as "--prefix=sub/", or is it a true string prefix? Reading more carefully, though, we say "under the directory at <prefix>" in the earlier part, which is probably sufficient.

Note that this _is_ different than "git checkout-index --prefix", which is a strict string prefix (i.e., you can checkout "--prefix=v1-" and get "v1-Makefile").

-Peff
[1] I was trying to figure out which feature of Git I was confusing it
    with, but couldn't find one. I think I may have just been thinking
    of checkout-index (which is not about matching existing paths, but
    does have the different behavior). Normally matching of existing
    paths is done with pathspecs, which I think should all use directory
    boundaries for prefix-matching.

← back to recent threads