Published 2023-03-30.
Last modified 2023-06-02.
Time to read: 4 minutes.
If you have ever needed to work on a relatively small portion of a large git repository, you know how slow things can get, and how problems arise with large files and directories. Two new features, partial clone and sparse checkout, can be used together to dramatically speed things up. Also, signifiantly less storage will be required on your computing device!
Git added a partial clone feature in version 2.24, via git clone --filter.
Git’s sparse checkout feature became user-friendly in version 2.25 with
the addition of the git sparse-checkout and git clone --sparse porcelain commands.
Definitions
By default, git repositories have up to 3 copies of every file. Copies can exist in git’s:
-
Working tree (also known as the working directory) –
this is where you edit files that you are currently working on.
The working tree consists of the contents of
.git/.., which is the the parent directory of the.gitdirectory. The contents of the.gitdirectory are not part of the working tree. -
Index (also known as the staging area, or the cache in older documentation) –
stored in
.git/index. When you rungit addorgit commit -a, a new snapshot of your working tree is saved to the index. -
Object database – stored in
.git/objects. When you rungit commit, the contents of the snapshots in the index are saved to the object database.
If you want to work on a subdirectory of a large git project, you may not want to have the entire project’s repository on your device. A partial clone, combined with the git sparse checkout feature allows you to just work on the subdirectory of interest in your repository.
Standalone Sparse Checkout
By itself, sparse checkout only affects the working tree, and hence the index.
In contrast, git’s object database is by default complete.
Sparse checkout means that for this local repository,
only selected portions of the repository’s object database are instantiated in the working tree.
When you git push from a sparse clone to a remote repository such as origin,
the snapshots contained in the local repository’s entire object database
are copied to the remote repository.
The integrity of the entire original repo is maintained. If someone else checks out the new repository, without performing the sparse checkout procedure, their working tree will populated from the complete contents of the original repository’s object database.
Shell
$ man git-sparse-checkout GIT-SPARSE-CHECKOU(1) Git Manual GIT-SPARSE-CHECKOU(1) NAME git-sparse-checkout - Reduce your working tree to a subset of tracked files SYNOPSIS git sparse-checkout (init | list | set | add | reapply | disable) [<options>] DESCRIPTION This command is used to create sparse checkouts, which change the working tree from having all tracked files present to only having a subset of those files. It can also switch which subset of files are present, or undo and go back to having all tracked files present in the working copy. The subset of files is chosen by providing a list of directories in cone mode (the default), or by providing a list of patterns in non-cone mode. When in a sparse-checkout, other Git commands behave a bit differently. For example, switching branches will not update paths outside the sparse-checkout directories/patterns, and git commit -a will not record paths outside the sparse-checkout directories/patterns as deleted. THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE. COMMANDS list Describe the directories or patterns in the sparse-checkout file. set Enable the necessary sparse-checkout config settings (core.sparseCheckout, core.sparseCheckoutCone, and index.sparse) if they are not already set to the desired values, populate the sparse-checkout file from the list of arguments following the set subcommand, and update the working directory to match. To ensure that adjusting the sparse-checkout settings within a worktree does not alter the sparse-checkout settings in other worktrees, the set subcommand will upgrade your repository config to use worktree-specific config if not already present. The sparsity defined by the arguments to the set subcommand are stored in the worktree-specific sparse-checkout file. See git- worktree(1) and the documentation of extensions.worktreeConfig in git-config(1) for more details. When the --stdin option is provided, the directories or patterns are read from standard in as a newline-delimited list instead of from the arguments. By default, the input list is considered a list of directories, matching the output of git ls-tree -d --name-only. This includes interpreting pathnames that begin with a double quote (") as C-style quoted strings. Note that all files under the specified directories (at any depth) will be included in the sparse checkout, as well as files that are siblings of either the given directory or any of its ancestors (see CONE PATTERN SET below for more details). In the past, this was not the default, and --cone needed to be specified or core.sparseCheckoutCone needed to be enabled. When --no-cone is passed, the input list is considered a list of patterns. This mode has a number of drawbacks, including not working with some options like --sparse-index. As explained in the "Non-cone Problems" section below, we do not recommend using it. Use the --[no-]sparse-index option to use a sparse index (the default is to not use it). A sparse index reduces the size of the index to be more closely aligned with your sparse-checkout definition. This can have significant performance advantages for commands such as git status or git add. This feature is still experimental. Some commands might be slower with a sparse index until they are properly integrated with the feature. WARNING: Using a sparse index requires modifying the index in a way that is not completely understood by external tools. If you have trouble with this compatibility, then run git sparse-checkout init --no-sparse-index to rewrite your index to not be sparse. Older versions of Git will not understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled. add Update the sparse-checkout file to include additional directories (in cone mode) or patterns (in non-cone mode). By default, these directories or patterns are read from the command-line arguments, but they can be read from stdin using the --stdin option. reapply Reapply the sparsity pattern rules to paths in the working tree. Commands like merge or rebase can materialize paths to do their work (e.g. in order to show you a conflict), and other sparse-checkout commands might fail to sparsify an individual file (e.g. because it has unstaged changes or conflicts). In such cases, it can make sense to run git sparse-checkout reapply later after cleaning up affected paths (e.g. resolving conflicts, undoing or committing changes, etc.). The reapply command can also take --[no-]cone and --[no-]sparse-index flags, with the same meaning as the flags from the set command, in order to change which sparsity mode you are using without needing to also respecify all sparsity paths. disable Disable the core.sparseCheckout config setting, and restore the working directory to include all files. init Deprecated command that behaves like set with no specified paths. May be removed in the future. Historically, set did not handle all the necessary config settings, which meant that both init and set had to be called. Invoking both meant the init step would first remove nearly all tracked files (and in cone mode, ignored files too), then the set step would add many of the tracked files (but not ignored files) back. In addition to the lost files, the performance and UI of this combination was poor. Also, historically, init would not actually initialize the sparse-checkout file if it already existed. This meant it was possible to return to a sparse-checkout without remembering which paths to pass to a subsequent set or add command. However, --cone and --sparse-index options would not be remembered across the disable command, so the easy restore of calling a plain init decreased in utility. EXAMPLES git sparse-checkout set MY/DIR1 SUB/DIR2 Change to a sparse checkout with all files (at any depth) under MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all files immediately under MY/ and SUB/ and the toplevel directory). If already in a sparse checkout, change which files are present in the working copy to this new selection. Note that this command will also delete all ignored files in any directory that no longer has either tracked or non-ignored-untracked files present. git sparse-checkout disable Repopulate the working directory with all files, disabling sparse checkouts. git sparse-checkout add SOME/DIR/ECTORY Add all files under SOME/DIR/ECTORY/ (at any depth) to the sparse checkout, as well as all files immediately under SOME/DIR/ and immediately under SOME/. Must already be in a sparse checkout before using this command. git sparse-checkout reapply It is possible for commands to update the working tree in a way that does not respect the selected sparsity directories. This can come from tools external to Git writing files, or even affect Git commands because of either special cases (such as hitting conflicts when merging/rebasing), or because some commands didn’t fully support sparse checkouts (e.g. the old recursive merge backend had only limited support). This command reapplies the existing sparse directory specifications to make the working directory match. INTERNALS — SPARSE CHECKOUT "Sparse checkout" allows populating the working directory sparsely. It uses the skip-worktree bit (see git-update- index(1)) to tell Git whether a file in the working directory is worth looking at. If the skip-worktree bit is set, and the file is not present in the working tree, then its absence is ignored. Git will avoid populating the contents of those files, which makes a sparse checkout helpful when working in a repository with many files, but only a few are important to the current user. The $GIT_DIR/info/sparse-checkout file is used to define the skip-worktree reference bitmap. When Git updates the working directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. INTERNALS — NON-CONE PROBLEMS The $GIT_DIR/info/sparse-checkout file populated by the set and add subcommands is defined to be a bunch of patterns (one per line) using the same syntax as .gitignore files. In cone mode, these patterns are restricted to matching directories (and users only ever need supply or see directory names), while in non-cone mode any gitignore-style pattern is permitted. Using the full gitignore-style patterns in non-cone mode has a number of shortcomings: • Fundamentally, it makes various worktree-updating processes (pull, merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern matches, where N is the number of patterns and M is the number of paths in the index. This scales poorly. • Avoiding the scaling issue has to be done via limiting the number of patterns via specifying leading directory name or glob. • Passing globs on the command line is error-prone as users may forget to quote the glob, causing the shell to expand it into all matching files and pass them all individually along to sparse-checkout set/add. While this could also be a problem with e.g. "git grep — *.c", mistakes with grep/log/status appear in the immediate output. With sparse-checkout, the mistake gets recorded at the time the sparse-checkout command is run and might not be problematic until the user later switches branches or rebases or merges, thus putting a delay between the user’s error and when they have a chance to catch/notice it. • Related to the previous item, sparse-checkout has an add subcommand but no remove subcommand. Even if a remove subcommand were added, undoing an accidental unquoted glob runs the risk of "removing too much", as it may remove entries that had been included before the accidental add. • Non-cone mode uses gitignore-style patterns to select what to include (with the exception of negated patterns), while .gitignore files use gitignore-style patterns to select what to exclude (with the exception of negated patterns). The documentation on gitignore-style patterns usually does not talk in terms of matching or non-matching, but on what the user wants to "exclude". This can cause confusion for users trying to learn how to specify sparse-checkout patterns to get their desired behavior. • Every other git subcommand that wants to provide "special path pattern matching" of some sort uses pathspecs, but non-cone mode for sparse-checkout uses gitignore patterns, which feels inconsistent. • It has edge cases where the "right" behavior is unclear. Two examples: First, two users are in a subdirectory, and the first runs git sparse-checkout set '/toplevel-dir/*.c' while the second runs git sparse-checkout set relative-dir Should those arguments be transliterated into current/subdirectory/toplevel-dir/*.c and current/subdirectory/relative-dir before inserting into the sparse-checkout file? The user who typed the first command is probably aware that arguments to set/add are supposed to be patterns in non-cone mode, and probably would not be happy with such a transliteration. However, many gitignore-style patterns are just paths, which might be what the user who typed the second command was thinking, and they'd be upset if their argument wasn't transliterated. Second, what should bash-completion complete on for set/add commands for non-cone users? If it suggests paths, is it exacerbating the problem above? Also, if it suggests paths, what if the user has a file or directory that begins with either a '!' or '#' or has a '*', '\', '?', '[', or ']' in its name? And if it suggests paths, will it complete "/pro" to "/proc" (in the root filesytem) rather than to "/progress.txt" in the current directory? (Note that users are likely to want to start paths with a leading '/' in non-cone mode, for the same reason that .gitignore files often have one.) Completing on files or directories might give nasty surprises in all these cases. • The excessive flexibility made other extensions essentially impractical. --sparse-index is likely impossible in non-cone mode; even if it is somehow feasible, it would have been far more work to implement and may have been too slow in practice. Some ideas for adding coupling between partial clones and sparse checkouts are only practical with a more restricted set of paths as well. For all these reasons, non-cone mode is deprecated. Please switch to using cone mode. INTERNALS — CONE MODE HANDLING The "cone mode", which is the default, lets you specify only what directories to include. For any directory specified, all paths below that directory will be included, and any paths immediately under leading directories (including the toplevel directory) will also be included. Thus, if you specified the directory Documentation/technical/ then your sparse checkout would contain: • all files in the toplevel-directory • all files immediately under Documentation/ • all files at any depth under Documentation/technical/ Also, in cone mode, even if no directories are specified, then the files in the toplevel directory will be included. When changing the sparse-checkout patterns in cone mode, Git will inspect each tracked directory that is not within the sparse-checkout cone to see if it contains any untracked files. If all of those files are ignored due to the .gitignore patterns, then the directory will be deleted. If any of the untracked files within that directory is not ignored, then no deletions will occur within that directory and a warning message will appear. If these files are important, then reset your sparse-checkout definition so they are included, use git add and git commit to store them, then remove any remaining files manually to ensure Git can behave optimally. See also the "Internals — Cone Pattern Set" section to learn how the directories are transformed under the hood into a subset of the Full Pattern Set of sparse-checkout. INTERNALS — FULL PATTERN SET The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules. These can result in O(N*M) pattern matches when updating the index, where N is the number of patterns and M is the number of paths in the index. To combat this performance issue, a more restricted pattern set is allowed when core.sparseCheckoutCone is enabled. The sparse-checkout file uses the same syntax as .gitignore files; see gitignore(5) for details. Here, though, the patterns are usually being used to select which files to include rather than which files to exclude. (However, it can get a bit confusing since gitignore-style patterns have negations defined by patterns which begin with a !, so you can also select files to not include.) For example, to select everything, and then to remove the file unwanted (so that every file will appear in your working tree except the file named unwanted): git sparse-checkout set --no-cone '/*' '!unwanted' These patterns are just placed into the $GIT_DIR/info/sparse-checkout as-is, so the contents of that file at this point would be /* !unwanted See also the "Sparse Checkout" section of git-read-tree(1) to learn more about the gitignore-style patterns used in sparse checkouts. INTERNALS — CONE PATTERN SET In cone mode, only directories are accepted, but they are translated into the same gitignore-style patterns used in the full pattern set. We refer to the particular patterns used in those mode as being of one of two types: 1. Recursive: All paths inside a directory are included. 2. Parent: All files immediately inside a directory are included. Since cone mode always includes files at the toplevel, when running git sparse-checkout set with no directories specified, the toplevel directory is added as a parent pattern. At this point, the sparse-checkout file contains the following patterns: /* !/*/ This says "include everything immediately under the toplevel directory, but nothing at any level below that." When in cone mode, the git sparse-checkout set subcommand takes a list of directories. The command git sparse-checkout set A/B/C sets the directory A/B/C as a recursive pattern, the directories A and A/B are added as parent patterns. The resulting sparse-checkout file is now /* !/*/ /A/ !/A/*/ /A/B/ !/A/B/*/ /A/B/C/ Here, order matters, so the negative patterns are overridden by the positive patterns that appear lower in the file. Unless core.sparseCheckoutCone is explicitly set to false, Git will parse the sparse-checkout file expecting patterns of these types. Git will warn if the patterns do not match. If the patterns do match the expected format, then Git will use faster hash-based algorithms to compute inclusion in the sparse-checkout. If they do not match, git will behave as though core.sparseCheckoutCone was false, regardless of its setting. In the cone mode case, despite the fact that full patterns are written to the $GIT_DIR/info/sparse-checkout file, the git sparse-checkout list subcommand will list the directories that define the recursive patterns. For the example sparse-checkout file above, the output is as follows: $ git sparse-checkout list A/B/C If core.ignoreCase=true, then the pattern-matching algorithm will use a case-insensitive check. This corrects for case mismatched filenames in the git sparse-checkout set command to reflect the expected cone in the working directory. INTERNALS — SUBMODULES If your repository contains one or more submodules, then submodules are populated based on interactions with the git submodule command. Specifically, git submodule init -- <path> will ensure the submodule at <path> is present, while git submodule deinit [-f] -- <path> will remove the files for the submodule at <path> (including any untracked files, uncommitted changes, and unpushed history). Similar to how sparse-checkout removes files from the working tree but still leaves entries in the index, deinitialized submodules are removed from the working directory but still have an entry in the index. Since submodules may have unpushed changes or untracked files, removing them could result in data loss. Thus, changing sparse inclusion/exclusion rules will not cause an already checked out submodule to be removed from the working copy. Said another way, just as checkout will not cause submodules to be automatically removed or initialized even when switching between branches that remove or add submodules, using sparse-checkout to reduce or expand the scope of "interesting" files will not cause submodules to be automatically deinitialized or initialized either. Further, the above facts mean that there are multiple reasons that "tracked" files might not be present in the working copy: sparsity pattern application from sparse-checkout, and submodule initialization state. Thus, commands like git grep that work on tracked files in the working copy may return results that are limited by either or both of these restrictions. SEE ALSO git-read-tree(1) gitignore(5) GIT Part of the git(1) suite Git 2.39.2 04/24/2023 GIT-SPARSE-CHECKOU(1)
As of the date this was written (2023-06-02),
the git-sparse-checkout command was still marked experimental.
The features and syntax have changed significantly since it was first proposed.
The git sparse-checkout init subcommand is
now deprecated and no longer recommended.
Non-cone mode is also deprecated.
Read about cones here.
Partial Clones
Partial clones work by specifying a filter that limits which objects are fetched. In the following examples, <repo> stands for the URL of a remote repository:
Shell
$ # omit all blobs $ git clone --filter=blob:none <repo> $ # omit blobs larger then 1 MB $ git clone --filter=blob:limit=1m <repo>
By default, partial clones retrieve missing objects when the user attempts to access them. Thus, a partial clone will grow larger over time unless sparse checkout is used in conjunction with a partial clone.
Sparse checkouts allow you to restrict the files and directories that git can retrieve from the remote repository. When sparse checkout is used with partial cloning, the two features work together so that not only is the size of the working tree reduced, but the git object database also reduced in size, so that only the requested objects are fetched from the remote repository, on demand.
Shell
$ man git-clone GIT-CLONE(1) Git Manual GIT-CLONE(1) NAME git-clone - Clone a repository into a new directory SYNOPSIS git clone [--template=<template-directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git-dir>] [--depth <depth>] [--[no-]single-branch] [--no-tags] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow] [--filter=<filter> [--also-filter-submodules]] [--] <repository> [<directory>] DESCRIPTION Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository (visible using git branch --remotes), and creates and checks out an initial branch that is forked from the cloned repository’s currently active branch. After the clone, a plain git fetch without arguments will update all the remote-tracking branches, and a git pull without arguments will in addition merge the remote master branch into the current master branch, if any (this is untrue when "--single-branch" is given; see below). This default configuration is achieved by creating references to the remote branch heads under refs/remotes/origin and by initializing remote.origin.url and remote.origin.fetch configuration variables. OPTIONS -l, --local When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. The files under .git/objects/ directory are hardlinked to save space when possible. If the repository is specified as a local path (e.g., /path/to/repo), this is the default, and --local is essentially a no-op. If the repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying --no-local will override the default when /path/to/repo is given, using the regular Git transport instead. NOTE: this operation can race with concurrent modification to the source repository, similar to running cp -r src dst while modifying src. --no-hardlinks Force the cloning process from a repository on a local filesystem to copy the files under the .git/objects directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. -s, --shared When the repository to clone is on the local machine, instead of using hard links, automatically setup .git/objects/info/alternates to share the objects with the source repository. The resulting repository starts out without any object of its own. NOTE: this is a possibly dangerous operation; do not use it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any other Git command that makes any existing commit unreferenced) in the source repository, some objects may become unreferenced (or dangling). These objects may be removed by normal Git operations (such as git commit) which automatically call git maintenance run --auto. (See git-maintenance(1).) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt. Note that running git repack without the --local option in a repository cloned with --shared will copy objects from the source repository into a pack in the cloned repository, removing the disk space savings of clone --shared. It is safe, however, to run git gc, which uses the --local option by default. If you want to break the dependency of a repository cloned with --shared on its source repository, you can simply run git repack -a to copy all objects from the source repository into a pack in the cloned repository. --reference[-if-able] <repository> If the reference repository is on the local machine, automatically setup .git/objects/info/alternates to obtain objects from the reference repository. Using an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs. When using the --reference-if-able, a non existing directory is skipped with a warning instead of aborting the clone. NOTE: see the NOTE for the --shared option, and also the --dissociate option. --dissociate Borrow the objects from reference repositories specified with the --reference options only to reduce network transfer, and stop borrowing from them after a clone is made by making necessary local copies of borrowed objects. This option can also be used when cloning locally from a repository that already borrows objects from another repository—the new repository will borrow objects from the same repository, and this option can be used to stop the borrowing. -q, --quiet Operate quietly. Progress is not reported to the standard error stream. -v, --verbose Run verbosely. Does not affect the reporting of progress status to the standard error stream. --progress Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --quiet is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. --server-option=<option> Transmit the given string to the server when communicating using protocol version 2. The given string must not contain a NUL or LF character. The server’s handling of server options, including unknown ones, is server-specific. When multiple --server-option=<option> are given, they are all sent to the other side in the order listed on the command line. -n, --no-checkout No checkout of HEAD is performed after the clone is complete. --[no-]reject-shallow Fail if the source repository is a shallow repository. The clone.rejectShallow configuration variable can be used to specify the default. --bare Make a bare Git repository. That is, instead of creating <directory> and placing the administrative files in <directory>/.git, make the <directory> itself the $GIT_DIR. This obviously implies the --no-checkout because there is nowhere to check out the working tree. Also the branch heads at the remote are copied directly to corresponding local branch heads, without mapping them to refs/remotes/origin/. When this option is used, neither remote-tracking branches nor the related configuration variables are created. --sparse Employ a sparse-checkout, with only files in the toplevel directory initially being present. The git-sparse- checkout(1) command can be used to grow the working directory as needed. --filter=<filter-spec> Use the partial clone feature and request that the server sends a subset of reachable objects according to a given object filter. When using --filter, the supplied <filter-spec> is used for the partial clone filter. For example, --filter=blob:none will filter out all blobs (file contents) until needed by Git. Also, --filter=blob:limit=<size> will filter out all blobs of size at least <size>. For more details on filter specifications, see the --filter option in git-rev- list(1). --also-filter-submodules Also apply the partial clone filter to any submodules in the repository. Requires --filter and --recurse-submodules. This can be turned on by default by setting the clone.filterSubmodules config option. --mirror Set up a mirror of the source repository. This implies --bare. Compared to --bare, --mirror not only maps local branches of the source to local branches of the target, it maps all refs (including remote-tracking branches, notes etc.) and sets up a refspec configuration such that all these refs are overwritten by a git remote update in the target repository. -o <name>, --origin <name> Instead of using the remote name origin to keep track of the upstream repository, use <name>. Overrides clone.defaultRemoteName from the config. -b <name>, --branch <name> Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository’s HEAD, point to <name> branch instead. In a non-bare repository, this is the branch that will be checked out. --branch can also take tags and detaches the HEAD at that commit in the resulting repository. -u <upload-pack>, --upload-pack <upload-pack> When given, and the repository to clone from is accessed via ssh, this specifies a non-default path for the command run on the other end. --template=<template-directory> Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of git-init(1).) -c <key>=<value>, --config <key>=<value> Set a configuration variable in the newly-created repository; this takes effect immediately after the repository is initialized, but before the remote history is fetched or any files checked out. The key is in the same format as expected by git-config(1) (e.g., core.eol=true). If multiple values are given for the same key, each value will be written to the config file. This makes it safe, for example, to add additional fetch refspecs to the origin remote. Due to limitations of the current implementation, some configuration variables do not take effect until after the initial fetch and checkout. Configuration variables known to not take effect are: remote.<name>.mirror and remote.<name>.tagOpt. Use the corresponding --mirror and --no-tags options instead. --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. --recurse-submodules[=<pathspec>] After the clone is created, initialize and clone submodules within based on the provided pathspec. If no pathspec is provided, all submodules are initialized and cloned. This option can be given multiple times for pathspecs consisting of multiple entries. The resulting clone has submodule.active set to the provided pathspec, or "." (meaning all submodules) if no pathspec is provided. Submodules are initialized and cloned using their default settings. This is equivalent to running git submodule update --init --recursive <pathspec> immediately after the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or --mirror is given) --[no-]shallow-submodules All submodules which are cloned will be shallow with a depth of 1. --[no-]remote-submodules All submodules which are cloned will use the status of the submodule’s remote-tracking branch to update the submodule, rather than the superproject’s recorded SHA-1. Equivalent to passing --remote to git submodule update. --separate-git-dir=<git-dir> Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, then make a filesystem-agnostic Git symbolic link to there. The result is Git repository can be separated from working tree. -j <n>, --jobs <n> The number of submodules fetched at the same time. Defaults to the submodule.fetchJobs option. <repository> The (possibly remote) repository to clone from. See the GIT URLS section below for more information on specifying repositories. <directory> The name of a new directory to clone into. The "humanish" part of the source repository is used if no directory is explicitly given (repo for /path/to/repo.git and foo for host.xz:foo/.git). Cloning into an existing directory is only allowed if the directory is empty. --bundle-uri=<uri> Before fetching from the remote, fetch a bundle from the given <uri> and unbundle the data into the local repository. The refs in the bundle will be stored under the hidden refs/bundle/* namespace. This option is incompatible with --depth, --shallow-since, and --shallow-exclude. GIT URLS In general, URLs contain information about the transport protocol, the address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, and ftps can be used for fetching, but this is inefficient and deprecated; do not use it). The native transport (i.e. git:// URL) does no authentication and should be used with caution on unsecured networks. The following syntaxes may be used with them: • ssh://[user@]host.xz[:port]/path/to/repo.git/ • git://host.xz[:port]/path/to/repo.git/ • http[s]://host.xz[:port]/path/to/repo.git/ • ftp[s]://host.xz[:port]/path/to/repo.git/ An alternative scp-like syntax may also be used with the ssh protocol: • [user@]host.xz:path/to/repo.git/ This syntax is only recognized if there are no slashes before the first colon. This helps differentiate a local path that contains a colon. For example the local path foo:bar could be specified as an absolute path or ./foo:bar to avoid being misinterpreted as an ssh url. The ssh and git protocols additionally support ~username expansion: • ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/ • git://host.xz[:port]/~[user]/path/to/repo.git/ • [user@]host.xz:/~[user]/path/to/repo.git/ For local repositories, also supported by Git natively, the following syntaxes may be used: • /path/to/repo.git/ • file:///path/to/repo.git/ These two syntaxes are mostly equivalent, except the former implies --local option. git clone, git fetch and git pull, but not git push, will also accept a suitable bundle file. See git-bundle(1). When Git doesn’t know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: • <transport>::<address> where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being invoked. See gitremote-helpers(7) for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a configuration section of the form: [url "<actual url base>"] insteadOf = <other url base> For example, with this: [url "git://git.host.xz/"] insteadOf = host.xz:/path/to/ insteadOf = work: a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". If you want to rewrite URLs for push only, you can create a configuration section of the form: [url "<actual url base>"] pushInsteadOf = <other url base> For example, with this: [url "ssh://example.org/"] pushInsteadOf = git://example.org/ a URL like "git://example.org/path/to/repo.git" will be rewritten to "ssh://example.org/path/to/repo.git" for pushes, but pulls will still use the original URL. EXAMPLES • Clone from upstream: $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux $ cd my-linux $ make • Make a local clone that borrows from the current directory, without checking things out: $ git clone -l -s -n . ../copy $ cd ../copy $ git show-branch • Clone from upstream while borrowing from an existing local directory: $ git clone --reference /git/linux.git \ git://git.kernel.org/pub/scm/.../linux.git \ my-linux $ cd my-linux • Create a bare repository to publish your changes to the public: $ git clone --bare -l /home/proj/.git /pub/scm/proj.git CONFIGURATION Everything below this line in this section is selectively included from the git-config(1) documentation. The content is the same as what’s found there: init.templateDir Specify the directory from which templates will be copied. (See the "TEMPLATE DIRECTORY" section of git- init(1).) init.defaultBranch Allows overriding the default branch name e.g. when initializing a new repository. clone.defaultRemoteName The name of the remote to create when cloning a repository. Defaults to origin, and can be overridden by passing the --origin command-line option to git-clone(1). clone.rejectShallow Reject to clone a repository if it is a shallow one, can be overridden by passing option --reject-shallow in command line. See git-clone(1) clone.filterSubmodules If a partial clone filter is provided (see --filter in git-rev-list(1)) and --recurse-submodules is used, also apply the filter to submodules. GIT Part of the git(1) suite Git 2.39.2 04/24/2023 GIT-CLONE(1)
Case Study
The project I wanted to work on was
Sinatra-ActiveRecord
and I wanted to play with the sample project for sqlite.
The sample project was very small (too small to be useful, actually!),
so it made no sense to fill my computing device with an overly large repository.
I wanted to eventually create two git remotes:
upstream– pointing to the original git repo,sinatra-activerecord/sinatra-activerecord.-
origin– pointing to a new repo in my GitHub account that will contain the complete original repo's contents and history, plus my changes. This repo will be calledmslinn/sinatra-activerecord-sqlite.
In the following command,
notice how I used the ‑‑origin option to name the upstream remote,
instead of using the default name, origin.
Shell
$ git clone \ --filter=blob:none \ --origin upstream \ --sparse \ https://github.com/sinatra-activerecord/sinatra-activerecord/ Cloning into 'sinatra-activerecord'... remote: Enumerating objects: 1020, done. remote: Counting objects: 100% (145/145), done. remote: Compressing objects: 100% (74/74), done. remote: Total 1020 (delta 41), reused 123 (delta 38), pack-reused 875 Receiving objects: 100% (1020/1020), 131.40 KiB | 3.86 MiB/s, done. Resolving deltas: 100% (245/245), done. remote: Enumerating objects: 9, done. remote: Counting objects: 100% (6/6), done. remote: Compressing objects: 100% (6/6), done. remote: Total 9 (delta 0), reused 0 (delta 0), pack-reused 3 Receiving objects: 100% (9/9), 6.15 KiB | 6.15 MiB/s, done. $ cd sinatra-activerecord/
The ‑‑filter=blob:none option in the above git clone command
suppressed all but the top-level population of the working tree.
The same thing would have happened if ‑‑filter=tree:0 had been
used instead of ‑‑filter=blob:none.
The only items in the working tree are the top-level files at this point:
Shell
$ ls -aF1 ./ ../ .git/ .gitignore Appraisals CHANGELOG.md CONTRIBUTING.md Gemfile LICENSE README.md Rakefile sinatra-activerecord.gemspec
Now we can ask for just the portions of the repository that interest us.
Notice that a checkout happens right after the git-sparse-checkout set command.
Directories specified by git-sparse-checkout must not have a leading slash.
Shell
$ git sparse-checkout set example/sqlite remote: Enumerating objects: 14, done. remote: Counting objects: 100% (1/1), done. remote: Total 14 (delta 0), reused 0 (delta 0), pack-reused 13 Receiving objects: 100% (14/14), 2.36 KiB | 2.36 MiB/s, done. Resolving deltas: 100% (1/1), done. $ git sparse-checkout list example/sqlite
Here are the files and directories that I just sparsely cloned from the repo:
shell continued
$ ls -af example/sqlite/ README.md ./ config/ app.rb Gemfile config.ru bin/ ../ Rakefile db/
Next I used the GitHub CLI to create a repo in my GitHub account
for containing the complete repo, along with my modifications.
This command created a remote called origin,
which points at the GitHub repo that was just created.
shell continued
$ gh repo create --public --source=. --remote=origin ✓ Created repository mslinn/sinatra-activerecord-sqlite on GitHub ✓ Added remote git@github.com:mslinn/sinatra-activerecord-sqlite.git
The above gh repo create command automatically names the repo from the current directory name.
I do this so often that I defined 2 bash aliases in ~/.bash_aliases:
~/.bash_aliases
alias gh_new_private='gh repo create --private --source=. --remote=origin' alias gh_new_public='gh repo create --public --source=. --remote=origin'