scalar(1)

@@ -2499,7 +2507,7 @@ users are expected to interact with directly. See --user-formats in git-help(1) for more details on the critera.

SYNOPSIS

scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
+scalar list
+scalar register [<enlistment>]
+scalar unregister [<enlistment>]
+scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
+scalar reconfigure [ --all | <enlistment> ]
+scalar diagnose [<enlistment>]
+scalar delete <enlistment>

DESCRIPTION

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.

An important Scalar concept is the enlistment: this is the top-level directory +of the project. It usually contains the subdirectory src/ which is a Git +worktree. This encourages the separation between tracked files (inside src/) +and untracked files, such as build artifacts (outside src/). When registering +an existing Git worktree with Scalar whose name is not src, the enlistment +will be identical to the worktree.

The scalar command implements various subcommands, and different options +depending on the subcommand. With the exception of clone, list and +reconfigure --all, all subcommands expect to be run in an enlistment.

The following options can be specified before the subcommand:

+-C <directory> +: +
+ Before running the subcommand, change the working directory. This + option imitates the same option of git(1). +
+
+-c <key>=<value> +: +
+ For the duration of running the specified subcommand, configure this + setting. This option imitates the same option of git(1). +
+

COMMANDS

Clone

+clone [<options>] <url> [<enlistment>] +: +
+ Clones the specified repository, similar to git-clone(1). By + default, only commit and tree objects are cloned. Once finished, the + worktree is located at <enlistment>/src. +
+
The sparse-checkout feature is enabled (except when run with --full-clone) +and the only files present are those in the top-level directory. Use +git sparse-checkout set to expand the set of directories you want to see, +or git sparse-checkout disable to expand to all files (see +git-sparse-checkout(1) for more details). You can explore the +subdirectories outside your sparse-checkout by using git ls-tree +HEAD[:<directory>].
+
+-b <name> +
+--branch <name> +: +
+ Instead of checking out the branch pointed to by the cloned + repository’s HEAD, check out the <name> branch instead. +
+
+--[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-]full-clone +: +
+ A sparse-checkout is initialized by default. This behavior can be + turned off via --full-clone. +
+

List

+list +: +
+ List enlistments that are currently registered by Scalar. This + subcommand does not need to be run inside an enlistment. +
+

Register

+register [<enlistment>] +: +
+ Adds the enlistment’s repository to the list of registered repositories + and starts background maintenance. If <enlistment> is not provided, + then the enlistment associated with the current working directory is + registered. +
+
Note: when this subcommand is called in a worktree that is called src/, its +parent directory is considered to be the Scalar enlistment. If the worktree is +not called src/, it itself will be considered to be the Scalar enlistment.
+

Unregister

+unregister [<enlistment>] +: +
+ Remove the specified repository from the list of repositories + registered with Scalar and stop the scheduled background maintenance. +
+

Run

+scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] +: +
+ Run the given maintenance task (or all tasks, if all was specified). + Except for all and config, this subcommand simply hands off to + git-maintenance(1) (mapping fetch to prefetch and + pack-files to incremental-repack). +
+
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.
+
The config 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 scalar clone +automatically, explicit invocations of this task are rarely needed.
+

Reconfigure

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.

With the --all option, all enlistments currently registered with Scalar +will be reconfigured. Use this option after each Scalar upgrade.

Diagnose

+diagnose [<enlistment>] +: +
+ 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. +
+
The output of this command is a .zip file that is written into +a directory adjacent to the worktree in the src directory.
+

Delete

+delete <enlistment> +: +
+ This subcommand lets you delete an existing Scalar enlistment from your + local file system, unregistering the repository. +
+

GIT

Part of the git(1) suite

Background

Scalar was originally designed as an add-on to Git and implemented as a .NET +Core application. It was created based on the learnings from the VFS for Git +project (another application aimed at improving the experience of working with +large repositories). As part of its initial implementation, Scalar relied on +custom features in the Microsoft fork of Git that have since been integrated +into core Git:

+
+partial clone, +
+
+
+commit graphs, +
+
+
+multi-pack index, +
+
+
+sparse checkout (cone mode), +
+
+
+scheduled background maintenance, +
+
+
+etc +
+

With the requisite Git functionality in place and a desire to bring the benefits +of Scalar to the larger Git community, the Scalar application itself was ported +from C# to C and integrated upstream.

Features

Scalar is comprised of two major pieces of functionality: automatically +configuring built-in Git performance features and managing repository +enlistments.

The Git performance features configured by Scalar (see "Background" for +examples) confer substantial performance benefits to large repositories, but are +either too experimental to enable for all of Git yet, or only benefit large +repositories. As new features are introduced, Scalar should be updated +accordingly to incorporate them. This will prevent the tool from becoming stale +while also providing a path for more easily bringing features to the appropriate +users.

Enlistments are how Scalar knows which repositories on a user’s system should +utilize Scalar-configured features. This allows it to update performance +settings when new ones are added to the tool, as well as centrally manage +repository maintenance. The enlistment structure - a root directory with a +src/ subdirectory containing the cloned repository itself - is designed to +encourage users to route build outputs outside of the repository to avoid the +performance-limiting overhead of ignoring those files in Git.

Design

Scalar is implemented in C and interacts with Git via a mix of child process +invocations of Git and direct usage of libgit.a. Internally, it is structured +much like other built-ins with subcommands (e.g., git stash), containing a +cmd_<subcommand>() function for each subcommand, routed through a cmd_main() +function. Most options are unique to each subcommand, with scalar respecting +some "global" git options (e.g., -c and -C).

Because scalar is not invoked as a Git subcommand (like git scalar), it is +built and installed as its own executable in the bin/ directory, alongside +git, git-gui, etc.

Main porcelain commands

Manipulation commands

Interrogation commands

Syncing repositories

+scalar(1) Manual Page +

NAME