Changeset View
Changeset View
Standalone View
Standalone View
documentation/content/en/articles/committers-guide/_index.adoc
Show All 12 Lines | |||||
It is optional if it is the main branch. | It is optional if it is the main branch. | ||||
'dir' is an optional directory to place it in (the default will be the name of the repo you are cloning (src, doc, etc)). | 'dir' is an optional directory to place it in (the default will be the name of the repo you are cloning (src, doc, etc)). | ||||
You will want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. | You will want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. | ||||
It is the easiest to keep up to date as well. | It is the easiest to keep up to date as well. | ||||
If you are interested in the history, but are working with only one branch and are short on space, you can also use --single-branch to only download the one branch | If you are interested in the history, but are working with only one branch and are short on space, you can also use --single-branch to only download the one branch | ||||
(though some merge commits will not reference the merged-from branch which may be important for some users who are interested in detailed versions of history). | (though some merge commits will not reference the merged-from branch which may be important for some users who are interested in detailed versions of history). | ||||
===== Partial Clone | |||||
If you are limited in bandwidth and/or local disk space, Git offers the possibility to filter the objects it requests from the repository when cloning using the https://www.git-scm.com/docs/partial-clone[Partial Clone] feature. | |||||
pauamma_gundo.com: s/If you are/If/ per FDP primer style guide. | |||||
The only drawback is that when you ask for information it does not have locally, Git will have to download the missing data, which it'll store locally, so you don't download something twice. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actionss/you ask/asking/ pauamma_gundo.com: s/you ask/asking/
s/you don't/it doesn't/ | |||||
The download is done under hood and you don't see it happening, the only thing you'll see is the command being a bit longer to return. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actions"Downloading happens under the hood, thus the command takes a bit longer to run." pauamma_gundo.com: "Downloading happens under the hood, thus the command takes a bit longer to run." | |||||
[NOTE] | |||||
====== | |||||
To explain what filtering is about, Git internally has three main kind of objects: | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actionss/kind/kinds/ pauamma_gundo.com: s/kind/kinds/ | |||||
* **blob**, which is used to store the content of a file. | |||||
* **tree**, which is a directory listing, it contains pointers to blobs, so the files in that directory, and other trees if it has sub directories. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actionss/listing, it contains/listing containing/ pauamma_gundo.com: s/listing, it contains/listing containing/
s/directory, and/directory and/ (no comma for 2… | |||||
* **commit**, which contain the actual commit, with author, date, message, and pointer to the root directorys tree, and parent commits. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actions"and pointers to the root directory tree and to the parent commit(s)" if I understand what you mean correctly (lowest directory in the tree below which all modified files are, reference to the single commit if not a merge, or to both or however many commits if a merge). pauamma_gundo.com: "and pointers to the root directory tree and to the parent commit(s)" if I understand what you… | |||||
Filtering will limit the kind/number/size of objects you are downloading. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actions"the kind, number, and or size of objects downloaded" pauamma_gundo.com: "the kind, number, and or size of objects downloaded" | |||||
====== | |||||
The most common filtering rules are | |||||
* `--filter=tree:0` which will download all the commits, but no tree or blobs. | |||||
* `--filter=blob:none` which will download all the commits and all the trees, but no blobs. | |||||
* `--filter=blob:limit=<n>[kmg]` which will download all the commits, all the trees, and only blobs that are smaller than the size limit. | |||||
What will also be included are all the trees and blobs needed to checkout either the main branch or the branch that has been requested on the command line. | |||||
pauamma_gundo.comUnsubmitted Not Done Inline Actions"the branch requested" pauamma_gundo.com: "the branch requested" | |||||
The full `--filter` arguments list can be found in the man:git-rev-list[1] man page. | |||||
[source,shell] | |||||
.... | |||||
% git clone -o freebsd --filter=tree:0 $URL [dir] | |||||
.... | |||||
===== Shallow Clone | ===== Shallow Clone | ||||
A shallow clone copies just the most current code, but none or little of the history. | A shallow clone copies just the most current code, but none or little of the history. | ||||
This can be useful when you need to build a specific revision of FreeBSD, or when you are just starting out and plan to track the tree more fully. | This can be useful when you need to build a specific revision of FreeBSD, or when you are just starting out and plan to track the tree more fully. | ||||
You can also use it to limit history to only so many revisions. | You can also use it to limit history to only so many revisions. | ||||
However, see below for a significant limitation of this approach. | However, see below for a significant limitation of this approach. | ||||
[source,shell] | [source,shell] | ||||
Show All 12 Lines |
s/If you are/If/ per FDP primer style guide.