From 73443f8dd5d97faf9a6199c5411ff391fe445fad Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 15 Feb 2021 18:19:40 +0700 Subject: [PATCH 1/3] Partial (and shallow) clone note Add note about partial and shallow clone, with external link describing them in detail. Signed-off-by: Bagas Sanjaya --- book/02-git-basics/sections/getting-a-repository.asc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc index 3b69efd08..3f5fc6e4d 100644 --- a/book/02-git-basics/sections/getting-a-repository.asc +++ b/book/02-git-basics/sections/getting-a-repository.asc @@ -82,6 +82,16 @@ $ git clone https://github.com/libgit2/libgit2 mylibgit That command does the same thing as the previous one, but the target directory is called `mylibgit`. +[NOTE] +.Partial and shallow clone +==== +Git version 2.22 and later introduce `--filter` option to `git clone`, which creates _partial clone_. Beside that, you can also get _shallow clone_ by specify `--depth` option. + +While partial and shallow clones can be useful on some situations (such as when cloning extremely large repository and cloning over metered connection), these come with their own tradeoffs that break at least one expectation from normal distribute nature of Git. If you aren't willing to make these tradeoffs, just do normal (full) clone (`git clone` without `--filter` or `--depth` options). + +We won't discuss further about partial and shallow clones, as these are for advanced users. Please see GitHub blog post at https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/ and GitLab documentation at https://docs.gitlab.com/ee/topics/git/partial_clone.html for complete discussion about these. +==== + Git has a number of different transfer protocols you can use. The previous example uses the `https://` protocol, but you may also see `git://` or `user@server:path/to/repo.git`, which uses the SSH transfer protocol. <> will introduce all of the available options the server can set up to access your Git repository and the pros and cons of each. From 6f362b1701dd67e471080111dc6fb9141f9f4d11 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Feb 2021 17:52:38 +0700 Subject: [PATCH 2/3] Apply suggestion from code review From @HonkingGoose: * Split paragraphs into one sentence each line Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- book/02-git-basics/sections/getting-a-repository.asc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc index 3f5fc6e4d..70704c105 100644 --- a/book/02-git-basics/sections/getting-a-repository.asc +++ b/book/02-git-basics/sections/getting-a-repository.asc @@ -85,11 +85,14 @@ That command does the same thing as the previous one, but the target directory i [NOTE] .Partial and shallow clone ==== -Git version 2.22 and later introduce `--filter` option to `git clone`, which creates _partial clone_. Beside that, you can also get _shallow clone_ by specify `--depth` option. +Git version 2.22 and later introduce `--filter` option to `git clone`, which creates _partial clone_. +Beside that, you can also get _shallow clone_ by specify `--depth` option. -While partial and shallow clones can be useful on some situations (such as when cloning extremely large repository and cloning over metered connection), these come with their own tradeoffs that break at least one expectation from normal distribute nature of Git. If you aren't willing to make these tradeoffs, just do normal (full) clone (`git clone` without `--filter` or `--depth` options). +While partial and shallow clones can be useful on some situations (such as when cloning extremely large repository and cloning over metered connection), these come with their own tradeoffs that break at least one expectation from normal distribute nature of Git. +If you aren't willing to make these tradeoffs, just do normal (full) clone (`git clone` without `--filter` or `--depth` options). -We won't discuss further about partial and shallow clones, as these are for advanced users. Please see GitHub blog post at https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/ and GitLab documentation at https://docs.gitlab.com/ee/topics/git/partial_clone.html for complete discussion about these. +We won't discuss further about partial and shallow clones, as these are for advanced users. +Please see GitHub blog post at https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/ and GitLab documentation at https://docs.gitlab.com/ee/topics/git/partial_clone.html for complete discussion about these. ==== Git has a number of different transfer protocols you can use. From 6a75486438d909c4d1560588cf1b4d8a0cca2fae Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Wed, 17 Feb 2021 17:50:06 +0700 Subject: [PATCH 3/3] Apply suggestion from code review Rewording from @HonkingGoose Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- .../sections/getting-a-repository.asc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc index 70704c105..d71e93d60 100644 --- a/book/02-git-basics/sections/getting-a-repository.asc +++ b/book/02-git-basics/sections/getting-a-repository.asc @@ -85,14 +85,17 @@ That command does the same thing as the previous one, but the target directory i [NOTE] .Partial and shallow clone ==== -Git version 2.22 and later introduce `--filter` option to `git clone`, which creates _partial clone_. -Beside that, you can also get _shallow clone_ by specify `--depth` option. +Git version 2.22 and later introduce the `--filter` option to `git clone`, which creates a _partial clone_. +Beside that, you can also get a _shallow clone_ by specifying the `--depth` option. -While partial and shallow clones can be useful on some situations (such as when cloning extremely large repository and cloning over metered connection), these come with their own tradeoffs that break at least one expectation from normal distribute nature of Git. -If you aren't willing to make these tradeoffs, just do normal (full) clone (`git clone` without `--filter` or `--depth` options). +Partial and shallow clones can be useful in some situations, like when you're cloning an extremely large repository or cloning over a metered connection. +The benefit of doing a partial or shallow clone is that the clone takes up less size on disk. +The drawback is that a partial or shallow clone breaks the normal behavior of Git. -We won't discuss further about partial and shallow clones, as these are for advanced users. -Please see GitHub blog post at https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/ and GitLab documentation at https://docs.gitlab.com/ee/topics/git/partial_clone.html for complete discussion about these. +If you don't want to deal with this complexity, just do a normal (full) clone (`git clone` without `--filter` or `--depth` options). + +We won't discuss partial and shallow clones in depth here, as these clones are for advanced users. +Please see the https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/[GitHub blog post about getting up to speed with partial clone and shallow clone^] and the https://docs.gitlab.com/ee/topics/git/partial_clone.html[GitLab documentation about partial clone^] for more information. ==== Git has a number of different transfer protocols you can use.