git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "Teng Long via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Teng Long <dyroneteng@gmail.com>
Subject: [PATCH v2 0/3] clone: document partial clone section
Date: Mon, 13 Apr 2020 15:25:57 +0000	[thread overview]
Message-ID: <pull.745.v2.git.git.1586791560.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.745.git.git.1585792946341.gitgitgadget@gmail.com>

Partial clones are created using 'git clone', but there is no related help
information in the git-clone documentation during a period. Add a relevant
section to help users understand what partial clones are and how they differ
from normal clones.

The section briefly introduces the applicable scenarios and some precautions
of partial clone. If users want to know more about its technical design and
other details, users can view the link of git-partial-clone(7) according to
the guidelines in the section.

Derrick Stolee (2):
  partial-clone: set default filter with --partial
  clone: document --partial and --filter options

Dyrone Teng (1):
  clone: document partial clone section

 Documentation/git-clone.txt   | 87 ++++++++++++++++++++++++++++++++++-
 list-objects-filter-options.c | 18 ++++++++
 list-objects-filter-options.h |  8 +++-
 t/t5616-partial-clone.sh      | 42 +++++++++++++----
 4 files changed, 143 insertions(+), 12 deletions(-)


base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v2
Pull-Request: https://github.com/git/git/pull/745

Range-diff vs v1:

 -:  ----------- > 1:  6f340d9aadf partial-clone: set default filter with --partial
 -:  ----------- > 2:  9baf4c8ba38 clone: document --partial and --filter options
 1:  f063efa545b ! 3:  c1a44a35095 clone: document partial clone section
     @@ Commit message
          clone: document partial clone section
      
          Partial clones are created using 'git clone', but there is no related
     -    help information in the git-clone documentation during a period. Add
     -    a relevant section to help users understand what partial clones are
     -    and how they differ from normal clones.
     +    help information in the git-clone documentation. Add a relevant section
     +    to help users understand what partial clones are and how they differ
     +    from normal clones.
      
          The section briefly introduces the applicable scenarios and some
          precautions of partial clone. If users want to know more about its
          technical design and other details, users can view the link of
          git-partial-clone(7) according to the guidelines in the section.
      
     -    Signed-off-by: Teng Long <dyroneteng@gmail.com>
     +    Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
      
       ## Documentation/git-clone.txt ##
      @@ Documentation/git-clone.txt: or `--mirror` is given)
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +-------------
      +
      +By default, `git clone` will download every reachable object, including
     -+every version of every file in the history of the repository. The **partial clone**
     -+feature allows Git to transfer fewer objects and request them from the
     -+remote only when they are needed, so some reachable objects can be
     -+omitted from the initial `git clone` and subsequent `git fetch`
     -+operations. In this way, a partial clone can reduce the network traffic
     -+costs and disk space usage when git is working under a large repository.
     ++every version of every file in the history of the repository. The
     ++**partial clone** feature allows Git to transfer fewer objects and
     ++request them from the remote only when they are needed, so some
     ++reachable objects can be omitted from the initial `git clone` and
     ++subsequent `git fetch` operations.
      +
      +To use the partial clone feature, you can run `git clone` with the 
     -+`--filter=<filter-spec>` option. If the repository has a deep history
     -+and you don't want to download any blobs, the form `filter=blob:none`
     -+will omit all the blobs. If the repository has some large blobs and you
     -+want to prevent some large blobs being downloaded by an appropriate
     -+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
     -+than n bytes or units (see linkgit:git-rev-list[1]).
     ++`--filter=<filter-spec>` option. If you want to clone a repository
     ++without download any blobs, the form `filter=blob:none` will omit all
     ++the blobs. If the repository has some large blobs and you want to
     ++prevent some large blobs being downloaded by an appropriate threshold,
     ++the form `--filter=blob:limit=<n>[kmg]`omits blobs larger than n bytes
     ++or units (see linkgit:git-rev-list[1]).
      +
     -+When using a partial clone, Git will request missing objects from the
     -+remote(s) when necessary. Several commands that do not involve a request
     -+over a network may now trigger these requests.
     ++As mentioned before, a partially cloned repository may have to request
     ++the missing objects when they are needed. So some 'local' commands may
     ++fail without a network connection to the remote repository.
      +
      +For example, The <repository> contains two branches which names 'master'
      +and 'topic. Then, we clone the repository by
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +were downloaded previously.
      +
      +`git log` may also make a surprise with partial clones. `git log
     -+--<path>` will not cause downloads with the blob filters, because it's
     -+only reading commits. `git log -p -- <path>` will download blobs to
     -+generate the patch output and git log --raw will download all blobs
     -+that changed at recent commits in order to compute renames.
     ++-- <pathspec>` will not cause downloads with the blob filters, because
     ++it's only reading commits and trees. In addition to any options that
     ++require git to look at the contents of blobs, like "-p" and "--stat"
     ++, options that cause git to report pathnames, like "--summary" and
     ++"--raw", will trigger lazy/on-demand fetching of blobs, as they are
     ++needed to detect inexact renames.
     ++
     ++linkgit:partial-clone[1]
      +
       :git-clone: 1
       include::urls.txt[]

-- 
gitgitgadget

  parent reply	other threads:[~2020-04-13 15:26 UTC|newest]

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-02  2:02 [PATCH] " Teng Long via GitGitGadget
2020-04-02 11:29 ` Derrick Stolee
2020-04-02 17:37 ` Junio C Hamano
2020-04-02 17:52   ` Derrick Stolee
2020-04-13 15:25 ` Teng Long via GitGitGadget [this message]
2020-04-13 15:25   ` [PATCH v2 1/3] partial-clone: set default filter with --partial Derrick Stolee via GitGitGadget
2020-04-13 15:25   ` [PATCH v2 2/3] clone: document --partial and --filter options Derrick Stolee via GitGitGadget
2020-04-13 15:26   ` [PATCH v2 3/3] clone: document partial clone section Dyrone Teng via GitGitGadget
2020-10-27 13:41     ` Philippe Blain
2020-04-13 22:45   ` [PATCH v2 0/3] " Junio C Hamano
2020-04-14 13:43     ` Derrick Stolee
2020-04-14 16:25       ` Junio C Hamano
2020-04-14 16:26         ` Derrick Stolee
2020-04-14 13:42   ` Derrick Stolee
2020-10-27  3:12   ` [PATCH v3] " Teng Long via GitGitGadget
2020-10-27 13:13     ` Philippe Blain
2020-10-27 18:51       ` Junio C Hamano
2021-02-25  9:13     ` [PATCH v4] " Teng Long via GitGitGadget
2021-02-25 13:38       ` Philippe Blain
2021-03-02 14:25       ` [PATCH v5] " Teng Long via GitGitGadget
2021-03-03 19:25         ` Junio C Hamano
2021-05-06  6:27           ` Fix inconsistent signed-off-by abd author name Teng Long
2021-05-06  6:30         ` [PATCH 1/1] clone: document partial clone section Teng Long
2021-05-07  4:00           ` Bagas Sanjaya

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=pull.745.v2.git.git.1586791560.gitgitgadget@gmail.com \
    --to=gitgitgadget@gmail.com \
    --cc=dyroneteng@gmail.com \
    --cc=git@vger.kernel.org \
    --subject='Re: [PATCH v2 0/3] clone: document partial clone section' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).