Manage a Large Git Repository with Scalar

Scalar exists because cloning a genuinely huge Git repository the ordinary way can take an age and leave a worktree nobody wants to touch. It applies performance-oriented configuration, registers the repository for background maintenance, and starts you off with a smaller working tree. This guide uses the Scalar shipped with Git 2.43.0. In about 15 minutes you will clone an enlistment, expand its sparse checkout, inspect maintenance registration, and remove it without guessing which directory is safe to delete.

Before you start

• Git 2.43.0 or a compatible install, plus network access to the repository.
• Enough disk space for the objects you choose to fetch.
• Write permission in the parent directory where the enlistment will live.

None of the commands below need root. Do not use sudo unless your chosen destination is deliberately managed by an administrator.

Scalar calls the project directory an enlistment. By default the Git worktree sits inside a src/ directory, while build output and other untracked material can sit beside it. That layout is useful, but it makes a careless rm -rf easy to aim at the wrong level. Keep the destination explicit.

1. Confirm the installed version

Check the executable before relying on examples from a different Git release:

scalar version
git --version

On the system used for this guide, the second command reports git version 2.43.0; Scalar is part of that Git suite. If scalar is not found, install the Git package that provides it through your normal operating system process, then repeat this check.

2. Clone with the deliberate defaults

Choose a URL and an enlistment name. This placeholder is safe to copy once you have replaced both values:

scalar clone https://git.example.invalid/team/project.git project

Unless you change the options, Scalar creates project/src/, enables sparse checkout showing only the top-level files, and clones only commit and tree objects. That is a useful starting point for a large codebase, not a promise that every file or every historical object is already local.

• --branch release when the branch to check out is not the remote's default.
• --single-branch when later fetches should update only the branch selected at clone time.
• --no-src if you need the worktree directly at project/ instead of project/src/.
• --full-clone if you need every file rather than the initial top-level sparse view.

Each of those choices changes the layout or checkout size, so record them in your project notes before someone assumes all branches or all files are available. None of them make deleting the directory later any less permanent.

Verify the result from the enlistment's worktree:

cd project/src
git status --short
git sparse-checkout list

An empty status is normal straight after a successful clone. git sparse-checkout list shows the current set of included paths. To inspect a directory outside that set without checking it out, use git ls-tree HEAD:directory.

3. Expand or disable sparse checkout

Expand the working view only when you actually need it, for example from project/src:

git sparse-checkout set src tools docs

The paths must exist in the repository and should match what your build or editor needs. To return to a full working tree:

git sparse-checkout disable

This changes the worktree, not the remote repository. If the expanded checkout eats more disk space than expected, run git sparse-checkout set again with a smaller list. Do not delete files by hand: Git will treat that as a local deletion, or leave the sparse definition inconsistent.

4. Register an existing worktree

Clone is not the only entry point. To give Scalar background maintenance for an existing repository, run scalar register from its enlistment, or pass the directory explicitly:

scalar register /srv/work/project
scalar list

When the worktree directory is named src, its parent is registered as the enlistment; for any other worktree name, that worktree itself is the enlistment. This distinction matters later when you unregister or delete it. Registration starts scheduled background maintenance; it does not publish changes or touch the remote.

scalar list works outside an enlistment and prints every repository currently registered with Scalar. An empty result means nothing is registered for the current user, not that some arbitrary Git repository is broken.

5. Run maintenance only when there is a reason

Registered repositories are maintained automatically, so manual runs are mainly useful for troubleshooting or a known maintenance point:

cd /srv/work/project/src
scalar run config
scalar run commit-graph

The available tasks are config, commit-graph, fetch, loose-objects, pack-files, and all. Scalar maps fetch to Git's prefetch task and pack-files to incremental repacking.

Warning: a full scalar run all may use noticeable CPU, disk, and network resources. Avoid starting it during a latency-sensitive build or on a host with limited bandwidth.

6. Repair configuration after an upgrade

After upgrading Scalar, reapply its configuration to one enlistment:

cd /srv/work/project/src
scalar reconfigure

To reconfigure every registered enlistment, run scalar reconfigure --all from any directory. That affects every repository registered for your user, so check scalar list first. Reconfiguration is not a substitute for recovering uncommitted work: check git status and preserve local changes before any operation that changes repository configuration.

7. Collect a diagnosis without changing the repository

When reporting a Scalar problem, run diagnosis from the enlistment:

cd /srv/work/project/src
scalar diagnose

Scalar writes a ZIP file of logs and repository statistics into a directory adjacent to the worktree in the src layout. Treat that archive as potentially sensitive: repository shape, paths and operational details can identify a private project, so review it before sending it to anyone.

8. Unregister first, delete only with a checkpoint

To stop scheduled maintenance while keeping the files, unregister the enlistment:

scalar unregister /srv/work/project
scalar list

This does not erase the Git repository. It only removes the registration and stops scheduled background maintenance; register it again with the same path if you change your mind.

Warning: scalar delete unregisters an enlistment and deletes it from the local file system. It is destructive. First inspect the path, check for uncommitted work, and copy anything you need:

cd /srv/work/project/src
git status --short
cd ../..
pwd
ls -la /srv/work/project
scalar delete /srv/work/project

There is no Scalar undo command for deleted local files. Recovery depends on another clone, a backup, or the remote repository, and uncommitted work may not exist anywhere else. Prefer scalar unregister when your goal is only to stop maintenance.

Done means

• scalar version and git --version identify the installation you are using.
• You know whether the worktree sits under enlistment/src or directly in the enlistment.
• git status --short is clean before any cleanup or reconfiguration.
• scalar list confirms the registration state.
• You change visibility with sparse-checkout commands rather than deleting tracked files by hand.
• scalar delete is reserved for a verified, backed-up enlistment; scalar unregister covers reversible maintenance control.