From: Philip Oakley Date: Tue, 24 Apr 2018 21:34:16 GMT Subject: Re: [PATCH v3 09/11] technical/shallow: describe the relationship with replace refs Message-ID: <538CF27C224E4AE0A1C45374AE367C3A@PhilipOakley> In-Reply-To: Hi dscho From: "Johannes Schindelin" : Tuesday, April 24, 2018 8:10 PM > On Sun, 22 Apr 2018, Philip Oakley wrote: > >> From: "Johannes Schindelin" >> > 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" >> > >> > Suggested-by: Eric Sunshine >> > Signed-off-by: Johannes Schindelin >> > --- >> > 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. > 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