Git and libgit2
Mike Slinn

Partial Clone With Sparse Checkout

Published 2023-03-30. Last modified 2023-06-02.
Time to read: 4 minutes.

This page is part of the git collection, categorized under Sinatra, git.

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:

  1. 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 .git directory. The contents of the .git directory are not part of the working tree.
  2. Index (also known as the staging area, or the cache in older documentation) – stored in .git/index. When you run git add or git commit -a, a new snapshot of your working tree is saved to the index.
  3. Object database – stored in .git/objects. When you run git 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 called mslinn/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'

References