git-commit-vandalism/contrib/scalar/scalar.txt

scalar(1)
=========

NAME
----
scalar - an opinionated repository management tool

SYNOPSIS
--------
[verse]
scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
scalar list
scalar register [<enlistment>]
scalar unregister [<enlistment>]

DESCRIPTION
-----------

Scalar is an opinionated repository management tool. By creating new
repositories or registering existing repositories with Scalar, your Git
experience will speed up. Scalar sets advanced Git config settings,
maintains your repositories in the background, and helps 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` and `list`, all
subcommands expect to be run in an enlistment.

COMMANDS
--------

Clone
~~~~~

clone [<options>] <url> [<enlistment>]::
	Clones the specified repository, similar to linkgit: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
linkgit: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.

SEE ALSO
--------
linkgit:git-clone[1], linkgit:git-maintenance[1].

Scalar
---
Associated with the linkgit:git[1] suite