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

From: Philip Oakley <philipoakley@iee.org>
Date: Apr 22, 2018, 15:16 UTC
Message-ID: <52C2C5A51FE7400E937F06B7641F4319@PhilipOakley>
In-Reply-To: <853b0a445ab1d78e8cbe19dacd09e70892b34b03.1524262793.git.johannes.schindelin@gmx.de>

From: "Johannes Schindelin" <johannes.schindelin@gmx.de>

Show 30 quoted lines

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

>                                               very much like the 
> deprecated
> +graft file (with

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

Show 14 quoted lines

> +different parents).
> +
> +This information is stored in a special-purpose file because the
> +user should not touch that file at all (even throughout
> +development of the shallow clone, it was never manually
> +edited!).
>
> Each line contains exactly one SHA-1. When read, a commit_graft
> will be constructed, which has nr_parent < 0 to make it easier
> -- 
> 2.17.0.windows.1.15.gaa56ade3205
>
>
>