Cloning

Conditional Clone

A repository contains commits, and a commit could contain trees(folder objects) and blobs(file objects). Sometimes you might need to conditionally exclude them on clone to save disk space. Git has special flags to do such job.

Filtering Commits

When a repository is especially large at size, and you're only interested in how to build the software from source, then it's a perfect scenario to apply --depth option in git. A depth is a integer representing the range of commits from new to old. When --depth=1 is specified, it means to fetch latest snapshot of the remote only.

The following repository has more than 8GB in total with full commits, while less than 500Mb with --depth=1 applied.

git clone git@github.com:NixOS/nixpkgs.git --depth 1

If you inspect the log you will find there's only one commit available on local.

[sharpchen@nixos:~/projects/nixpkgs]$ git log --pretty=format:"%H"
6e00a2ec0af992e46494f5700c631101090271ca

NOTE

Using --depth to generate a clone is also called as shallow clone To recover your repository to a full clone, use git fetch --unshallow

Filtering Blobs

Blobs are file abstraction in git, when --filter=blob:none is specified on clone, git will not fetch files besides HEAD on this clone. Git will defer the fetch when you access any other blobs from commits that are not downloaded on local. That is, --filter=blob:none is a lazy initialization of the repository.

git clone git@github.com:NixOS/nixpkgs.git --filter=blob:none

NOTE

git fetch on a blobless repository will only fetch new commits from remote, it doesn't recover it to full repository.

Filtering Trees

--filter=tree:0 is similar to --filter=blob:none but even slimmer. The whole structure including tree and blob are lazily initialized.

git clone git@github.com:NixOS/nixpkgs.git --filter=tree:0

Conclusion

If you want a slime clone: - if you don't care commit history, use --depth=1(which is the slimmest approach) - if you care only commits history, use --filter=tree:0 - TODO: explain why do I need blob:none when tree:0 is available?

Clone with Submodule

Fetching submodule on clone:

git clone <url> --recursive

If you forgot to append --recursive option when cloning for the first time, you can still remedy using the following command.

git submodule update --init --recursive