git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH V5 2/2] user-manual: add section documenting shallow clones

From
Junio C Hamano <gitster@pobox.com>
Date
Dec 29, 2015, 19:24 UTC
Message-ID
<xmqqtwn1gisv.fsf@gitster.mtv.corp.google.com>
In-Reply-To
<1451415296-3960-1-git-send-email-ischis2@cox.net>
"Stephen P. Smith" <ischis2@cox.net> writes:
Show 5 quoted lines
> Rather than merely pointing readers at the 1.5 release notes to
> learn about shallow clones, document them formally.
>
> Signed-off-by: Stephen P. Smith <ischis2@cox.net>
> ---

Thanks. I do not think the reference to RelNotes were meant for the end-user readers, though. That was a hint for whoever is working to clear the "todo" items from that list i.e. you ;-).

Show 16 quoted lines
> +[[how-to-get-a-git-repository-with-minimal-history]]
> +How to get a Git repository with minimal history
> +------------------------------------------------
> +
> +A <<def_shallow_clone,shallow clone>>, with its truncated
> +history, is useful when one is interested only in recent history
> +of a project and getting full history from the upstream is
> +expensive.
> +
> +A <<def_shallow_clone,shallow clone>> is created by specifying
> +the linkgit:git-clone[1] `--depth` switch. The depth can later be
> +changed with the linkgit:git-fetch[1] `--depth` switch, or full
> +history restored with `--unshallow`.
> +
> +Merging inside a <<def_shallow_clone,shallow clone>> will work as long
> +as the merge base is in the resent history.  If the merge base is not
recent?
> +present then the merge would be of un-related histories.  This
> +limitaion is fundamental and will not be removed.

I think "fundamental and will not change" is much less important than the "huge conflicts, making the result of 'clone --depth=<n>' not very useful to perform merges in", which is what the users would need to know before deciding to use this feature.

Show 13 quoted lines
> +
>  [[sharing-development-examples]]
>  Examples
>  --------
> @@ -4645,9 +4664,6 @@ standard end-of-chapter section?
>  
>  Include cross-references to the glossary, where appropriate.
>  
> -Document shallow clones?  See draft 1.5.0 release notes for some
> -documentation.
> -
>  Add a section on working with other version control systems, including
>  CVS, Subversion, and just imports of series of release tarballs.
Previous: Stephen P. SmithNext: Stephen & Linda Smith
Message 12 of 22 in “Define the term shallow clone.”
  1. 1/2 Define the term shallow clone.Stephen P. Smith, Dec 22, 2015
  2. 2/2 Add a section to the users manual documenting shallow clones.Stephen P. Smith, Dec 22, 2015
  3. Eric SunshineDec 22, 2015
  4. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 22, 2015
  5. Stephen & Linda SmithDec 23, 2015
  6. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 23, 2015
  7. Eric SunshineDec 23, 2015
  8. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 23, 2015
  9. Junio C HamanoDec 28, 2015
  10. 1/2 glossary: define the term shallow cloneStephen P. Smith, Dec 29, 2015
  11. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 29, 2015
  12. Junio C HamanoDec 29, 2015
  13. Stephen & Linda SmithDec 29, 2015
  14. Junio C HamanoDec 29, 2015
  15. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 29, 2015
  16. Junio C HamanoDec 29, 2015
  17. 2/2 user-manual: add section documenting shallow clonesStephen P. Smith, Dec 30, 2015
  18. Stephen & Linda SmithDec 29, 2015
  19. Stephen & Linda SmithDec 22, 2015
  20. Eric SunshineDec 22, 2015
  21. 1/2 glossary: define the term shallow cloneStephen P. Smith, Dec 22, 2015
  22. 1/2 glossary: define the term shallow cloneStephen P. Smith, Dec 23, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.