Doku Wiki

Basic and advanced features of cloning.

Read all about it here.

Synopsis:

--depth <depth>
    Create a shallow clone with a history truncated to the
    specified number of commits. Implies --single-branch unless
    --no-single-branch is given to fetch the histories near the
    tips of all branches. If you want to clone submodules
    shallowly, also pass --shallow-submodules.

--shallow-since=<date>
    Create a shallow clone with a history after the specified
    time.

--shallow-exclude=<revision>
    Create a shallow clone with a history, excluding commits
    reachable from a specified remote branch or tag. This
    option can be specified multiple times.

--[no-]single-branch
    Clone only the history leading to the tip of a single
    branch, either specified by the --branch option or the
    primary branch remote’s HEAD points at. Further fetches
    into the resulting repository will only update the
    remote-tracking branch for the branch this option was used
    for the initial cloning. If the HEAD at the remote did not
    point at any branch when --single-branch clone was made, no
    remote-tracking branch is created.

--no-tags
    Don’t clone any tags, and set
    remote.<remote>.tagOpt=--no-tags in the config, ensuring
    that future git pull and git fetch operations won’t follow
    any tags. Subsequent explicit tag fetches will still work,
    (see git-fetch(1)).

    Can be used in conjunction with --single-branch to clone
    and maintain a branch with no references other than a
    single cloned branch. This is useful e.g. to maintain
    minimal clones of the default branch of some repository for
    search indexing.

Example:

$ git clone --depth 1 --single-branch <repo URL>

From here:

Side note: there's also narrow/lazy clone (or something with the
promisor) but I still haven't caught up with that. So none of that
here, but I think we should eventually have some examples/description.

A shallow clone is basically a repository with commit history cut
short. If you have a commit though, you have full content. It's not
cut by paths or anything.

"git clone --depth=X" the the normal way to do this. You get a
repository where all branches and tags have maximum X commits deep.
But since the main purpose of shallow clone is redude download,
--single-branch is made default when --depth is present, so you get
the default branch instead of all the branches (you would need
--no-single-branch for that). You could see these cut points with "git
log --decorate". I think they are marked "crafted" or something.

Once you have made a shallow clone, you could do everything like
usual. Local operations of course can only reach as far as the cut
points. Pull and push to a full clone are possible (it's even possible
to do so to another shallow clone).

When you "git fetch", the cut points remain the same, so you get more
recent commits and the history depth increases. If you do "git fetch
--depth=X" then the cut points are adjusted so that you only have
maximum X commits deep for all select branches, the same way a shallow
clone is made initially. "git fetch --unshallow" can be used to turn a
shallow clone into a complete one. And I'm pretty sure you could turn
a complete one to shallow with "git fetch --depth".

While --depth works fine most of the time, sometimes you want a
different way to define these shallow/cut points. --shallow-since and
--shallow-exclude are added as the result. --shallow-since cut the
history by a specific date (for all select branches).
--shallow-exclude cuts the history by a ref (often a tag). As I
mentioned before, it's mostly used to say "I want a shallow clone from
(but not including) v2.9.0".

And I think that's pretty much it. There's --update-shallow option but
I can't remember when that's needed. Shallow clones may also prevent
you from using some optional features. Pack bitmap is one of those and
I think probably commit graph too. It's not technical limitation, just
lack of time/effort to support them in shallow clones.
-- 
Duy