Re: [PATCH v3 09/11] technical/shallow: describe the relationship with replace refs

From: Philip Oakley <philipoakley@iee.org>
Date: Apr 24, 2018, 21:34 UTC
Message-ID: <538CF27C224E4AE0A1C45374AE367C3A@PhilipOakley>
In-Reply-To: <nycvar.QRO.7.76.6.1804242106220.64@ZVAVAG-6OXH6DA.rhebcr.pbec.zvpebfbsg.pbz>

Hi dscho

From: "Johannes Schindelin" <Johannes.Schindelin@gmx.de> : Tuesday, April 
24, 2018 8:10 PM

Show 6 quoted lines

> On Sun, 22 Apr 2018, Philip Oakley wrote:
>
>> From: "Johannes Schindelin" <johannes.schindelin@gmx.de>
>> > Now that grafts are deprecated, we should start to assume that readers
>> > have no idea what grafts are. So it makes more sense to describe the
>> > "shallow" feature in terms of replace refs.

Here we say we should drop the term "grafts"

Show 32 quoted lines

>> >
>> > Suggested-by: Eric Sunshine <sunshine@sunshineco.com>
>> > Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
>> > ---
>> > Documentation/technical/shallow.txt | 19 +++++++++++--------
>> > 1 file changed, 11 insertions(+), 8 deletions(-)
>> >
>> > diff --git a/Documentation/technical/shallow.txt
>> > b/Documentation/technical/shallow.txt
>> > index 5183b154229..b3ff23c25f6 100644
>> > --- a/Documentation/technical/shallow.txt
>> > +++ b/Documentation/technical/shallow.txt
>> > @@ -9,14 +9,17 @@ these commits have no parents.
>> > *********************************************************
>> >
>> > The basic idea is to write the SHA-1s of shallow commits into
>> > -$GIT_DIR/shallow, and handle its contents like the contents
>> > -of $GIT_DIR/info/grafts (with the difference that shallow
>> > -cannot contain parent information).
>> > -
>> > -This information is stored in a new file instead of grafts, or
>> > -even the config, since the user should not touch that file
>> > -at all (even throughout development of the shallow clone, it
>> > -was never manually edited!).
>> > +$GIT_DIR/shallow, and handle its contents similar to replace
>> > +refs (with the difference that shallow does not actually
>> > +create those replace refs) and
>>
>> If grafts are deprecated, why not alse get rid of this mention and simply
>> leave the 'what it does' part.
>
> Internally, shallow commits are implemented using the graft code path, and

however the change here is just to the documentation, independent of th code path's name.

Show 10 quoted lines

> they always will be: we will always need a list of the shallow commits,
> and we will always need to be able to lift the "shallow" attribute
> quickly, when deepening a shallow clone.
>
> So it makes sense to mention that here, because we are deep in technical
> details in Documentation/technical/.
>
>> >                                               very much like the 
>> > deprecated
>> > +graft file (with

I was looking to snip this 'graft' reference, as per the commit message..

>>
>> >                           the difference that shallow commits will
>> > +always have their parents grafted away, not replaced by
>> s/their parents grafted away/no parents/ (rather than being replaced..)

Then I botched this substitution

>
> But the commits will typically have parents. So they really will have
> their parents grafted away as long as they are marked "shallow"...

OK, maybe I mis-used the figurative 'no parents', when it means the literal 'parents not present'.

Perhaps something like: +$GIT_DIR/shallow, and handle its contents similar to replace +refs (with the difference that shallow does not actually +create those replace refs) with the difference that shallow commits will +always have their parents not present.

-- Philip