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

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

[Andreas G. Schacker]

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

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

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

[Junio C Hamano]

"Andreas G. Schacker" <andreas.schacker@gmail.com> writes:

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



>  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

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

[Jeff King]

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

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

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

[Jeff King]

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.

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

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

[Jeff King]

On Thu, Jan 11, 2018 at 03:14:07PM -0800, Junio C Hamano wrote:

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