man1/scalar.1

'\" t
.\"     Title: scalar
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2025-10-07
.\"    Manual: Git Manual
.\"    Source: Git 2.51.0.463.g79cf913ea9
.\"  Language: English
.\"
.TH "SCALAR" "1" "2025-10-07" "Git 2\&.51\&.0\&.463\&.g79cf91" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
scalar \- A tool for managing large Git repositories
.SH "SYNOPSIS"
.sp
.nf
scalar clone [\-\-single\-branch] [\-\-branch <main\-branch>] [\-\-full\-clone]
        [\-\-[no\-]src] [\-\-[no\-]tags] [\-\-[no\-]maintenance] <url> [<enlistment>]
scalar list
scalar register [\-\-[no\-]maintenance] [<enlistment>]
scalar unregister [<enlistment>]
scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
scalar reconfigure [\-\-maintenance=(enable|disable|keep)] [ \-\-all | <enlistment> ]
scalar diagnose [<enlistment>]
scalar delete <enlistment>
.fi
.SH "DESCRIPTION"
.sp
Scalar is a repository management tool that optimizes Git for use in large repositories\&. Scalar improves performance by configuring advanced Git settings, maintaining repositories in the background, and helping to reduce data sent across the network\&.
.sp
An important Scalar concept is the enlistment: this is the top\-level directory of the project\&. It usually contains the subdirectory \fBsrc/\fR which is a Git worktree\&. This encourages the separation between tracked files (inside \fBsrc/\fR) and untracked files, such as build artifacts (outside \fBsrc/\fR)\&. When registering an existing Git worktree with Scalar whose name is not \fBsrc\fR, the enlistment will be identical to the worktree\&.
.sp
The \fBscalar\fR command implements various subcommands, and different options depending on the subcommand\&. With the exception of \fBclone\fR, \fBlist\fR and \fBreconfigure\fR \fB\-\-all\fR, all subcommands expect to be run in an enlistment\&.
.sp
The following options can be specified \fIbefore\fR the subcommand:
.PP
\-C <directory>
.RS 4
Before running the subcommand, change the working directory\&. This option imitates the same option of
\fBgit\fR(1)\&.
.RE
.PP
\-c <key>=<value>
.RS 4
For the duration of running the specified subcommand, configure this setting\&. This option imitates the same option of
\fBgit\fR(1)\&.
.RE
.SH "COMMANDS"
.SS "Clone"
.PP
clone [<options>] <url> [<enlistment>]
.RS 4
Clones the specified repository, similar to
\fBgit-clone\fR(1)\&. By default, only commit and tree objects are cloned\&. Once finished, the worktree is located at
\fI<enlistment>\fR\fB/src\fR\&.
.sp
The sparse\-checkout feature is enabled (except when run with
\fB\-\-full\-clone\fR) and the only files present are those in the top\-level directory\&. Use
\fBgit\fR
\fBsparse\-checkout\fR
\fBset\fR
to expand the set of directories you want to see, or
\fBgit\fR
\fBsparse\-checkout\fR
\fBdisable\fR
to expand to all files (see
\fBgit-sparse-checkout\fR(1)
for more details)\&. You can explore the subdirectories outside your sparse\-checkout by using
\fBgit\fR
\fBls\-tree\fR
\fBHEAD\fR[\fB:\fR\fI<directory>\fR]\&.
.RE
.PP
\-b <name>, \-\-branch <name>
.RS 4
Instead of checking out the branch pointed to by the cloned repository\(cqs HEAD, check out the
\fI<name>\fR
branch instead\&.
.RE
.PP
\-\-single\-branch, \-\-no\-single\-branch
.RS 4
Clone only the history leading to the tip of a single branch, either specified by the
\fB\-\-branch\fR
option or the primary branch remote\(cqs
\fBHEAD\fR
points at\&.
.sp
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
\fB\-\-single\-branch\fR
clone was made, no remote\-tracking branch is created\&.
.RE
.PP
\-\-src, \-\-no\-src
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
places the cloned repository within a
\fI<entlistment>\fR\fB/src\fR
directory\&. Use
\fB\-\-no\-src\fR
to place the cloned repository directly in the
\fI<enlistment>\fR
directory\&.
.RE
.PP
\-\-tags, \-\-no\-tags
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
will fetch the tag objects advertised by the remote and future
\fBgit\fR
\fBfetch\fR
commands will do the same\&. Use
\fB\-\-no\-tags\fR
to avoid fetching tags in
\fBscalar\fR
\fBclone\fR
and to configure the repository to avoid fetching tags in the future\&. To fetch tags after cloning with
\fB\-\-no\-tags\fR, run
\fBgit\fR
\fBfetch\fR
\fB\-\-tags\fR\&.
.RE
.PP
\-\-full\-clone, \-\-no\-full\-clone
.RS 4
A sparse\-checkout is initialized by default\&. This behavior can be turned off via
\fB\-\-full\-clone\fR\&.
.RE
.PP
\-\-maintenance, \-\-no\-maintenance
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
configures the enlistment to use Git\(cqs background maintenance feature\&. Use the
\fB\-\-no\-maintenance\fR
to skip this configuration\&.
.RE
.SS "List"
.PP
list
.RS 4
List enlistments that are currently registered by Scalar\&. This subcommand does not need to be run inside an enlistment\&.
.RE
.SS "Register"
.PP
register [<enlistment>]
.RS 4
Adds the enlistment\(cqs repository to the list of registered repositories and starts background maintenance\&. If
\fI<enlistment>\fR
is not provided, then the enlistment associated with the current working directory is registered\&.
.sp
Note: when this subcommand is called in a worktree that is called
\fBsrc/\fR, its parent directory is considered to be the Scalar enlistment\&. If the worktree is
\fInot\fR
called
\fBsrc/\fR, it itself will be considered to be the Scalar enlistment\&.
.RE
.PP
\-\-maintenance, \-\-no\-maintenance
.RS 4
By default,
\fBscalar\fR
\fBregister\fR
configures the enlistment to use Git\(cqs background maintenance feature\&. Use the
\fB\-\-no\-maintenance\fR
to skip this configuration\&. This does not disable any maintenance that may already be enabled in other ways\&.
.RE
.SS "Unregister"
.PP
unregister [<enlistment>]
.RS 4
Remove the specified repository from the list of repositories registered with Scalar and stop the scheduled background maintenance\&.
.RE
.SS "Run"
.PP
scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
.RS 4
Run the given maintenance task (or all tasks, if
\fBall\fR
was specified)\&. Except for
\fBall\fR
and
\fBconfig\fR, this subcommand simply hands off to
\fBgit-maintenance\fR(1)
(mapping
\fBfetch\fR
to
\fBprefetch\fR
and
\fBpack\-files\fR
to
\fBincremental\-repack\fR)\&.
.sp
These tasks are run automatically as part of the scheduled maintenance, as soon as the repository is registered with Scalar\&. It should therefore not be necessary to run this subcommand manually\&.
.sp
The
\fBconfig\fR
task is specific to Scalar and configures all those opinionated default settings that make Git work more efficiently with large repositories\&. As this task is run as part of
\fBscalar\fR
\fBclone\fR
automatically, explicit invocations of this task are rarely needed\&.
.RE
.SS "Reconfigure"
.sp
After a Scalar upgrade, or when the configuration of a Scalar enlistment was somehow corrupted or changed by mistake, this subcommand allows to reconfigure the enlistment\&.
.PP
\-\-all
.RS 4
When
\fB\-\-all\fR
is specified, reconfigure all enlistments currently registered with Scalar by the
\fBscalar\&.repo\fR
config key\&. Use this option after each upgrade to get the latest features\&.
.RE
.PP
\-\-maintenance=(enable|disable|keep)
.RS 4
By default, Scalar configures the enlistment to use Git\(cqs background maintenance feature; this is the same as using the
\fBenable\fR
value for this option\&. Use the
\fBdisable\fR
value to remove each considered enlistment from background maintenance\&. Use
\(lqkeep\(rq
to leave the background maintenance configuration untouched for these repositories\&.
.RE
.SS "Diagnose"
.PP
diagnose [<enlistment>]
.RS 4
When reporting issues with Scalar, it is often helpful to provide the information gathered by this command, including logs and certain statistics describing the data shape of the current enlistment\&.
.sp
The output of this command is a \&.\fBzip\fR
file that is written into a directory adjacent to the worktree in the
\fBsrc\fR
directory\&.
.RE
.SS "Delete"
.PP
delete <enlistment>
.RS 4
This subcommand lets you delete an existing Scalar enlistment from your local file system, unregistering the repository\&.
.RE
.SH "SEE ALSO"
.sp
\fBgit-clone\fR(1), \fBgit-maintenance\fR(1)\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite