Merge branch 'vd/scalar-to-main'
Hoist the remainder of "scalar" out of contrib/ to the main part of the codebase. * vd/scalar-to-main: Documentation/technical: include Scalar technical doc t/perf: add 'GIT_PERF_USE_SCALAR' run option t/perf: add Scalar performance tests scalar-clone: add test coverage scalar: add to 'git help -a' command list scalar: implement the `help` subcommand git help: special-case `scalar` scalar: include in standard Git build & installation scalar: fix command documentation section header
This commit is contained in:
Junio C Hamano
@ -21,6 +21,7 @@ MAN1_TXT += $(filter-out \
|
||||
MAN1_TXT += git.txt
|
||||
MAN1_TXT += gitk.txt
|
||||
MAN1_TXT += gitweb.txt
|
||||
MAN1_TXT += scalar.txt
|
||||
|
||||
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
|
||||
MAN5_TXT += gitattributes.txt
|
||||
@ -116,6 +117,7 @@ TECH_DOCS += technical/parallel-checkout
|
||||
TECH_DOCS += technical/partial-clone
|
||||
TECH_DOCS += technical/racy-git
|
||||
TECH_DOCS += technical/reftable
|
||||
TECH_DOCS += technical/scalar
|
||||
TECH_DOCS += technical/send-pack-pipeline
|
||||
TECH_DOCS += technical/shallow
|
||||
TECH_DOCS += technical/trivial-merge
|
||||
|
||||
@ -10,7 +10,7 @@ sub format_one {
|
||||
$state = 0;
|
||||
open I, '<', "$name.txt" or die "No such file $name.txt";
|
||||
while (<I>) {
|
||||
if (/^git[a-z0-9-]*\(([0-9])\)$/) {
|
||||
if (/^(git|scalar)[a-z0-9-]*\(([0-9])\)$/) {
|
||||
$mansection = $1;
|
||||
next;
|
||||
}
|
||||
|
||||
166
Documentation/scalar.txt
Normal file
166
Documentation/scalar.txt
Normal file
@ -0,0 +1,166 @@
|
||||
scalar(1)
|
||||
=========
|
||||
|
||||
NAME
|
||||
----
|
||||
scalar - A tool for managing large Git repositories
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
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 linkgit:git[1].
|
||||
|
||||
-c <key>=<value>::
|
||||
For the duration of running the specified subcommand, configure this
|
||||
setting. This option imitates the same option of linkgit:git[1].
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
linkgit: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.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
linkgit:git-clone[1], linkgit:git-maintenance[1].
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -64,64 +64,3 @@ 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.
|
||||
|
||||
Roadmap
|
||||
-------
|
||||
|
||||
NOTE: this section will be removed once the remaining tasks outlined in this
|
||||
roadmap are complete.
|
||||
|
||||
Scalar is a large enough project that it is being upstreamed incrementally,
|
||||
living in `contrib/` until it is feature-complete. So far, the following patch
|
||||
series have been accepted:
|
||||
|
||||
- `scalar-the-beginning`: The initial patch series which sets up
|
||||
`contrib/scalar/` and populates it with a minimal `scalar` command that
|
||||
demonstrates the fundamental ideas.
|
||||
|
||||
- `scalar-c-and-C`: The `scalar` command learns about two options that can be
|
||||
specified before the command, `-c <key>=<value>` and `-C <directory>`.
|
||||
|
||||
- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.
|
||||
|
||||
- `scalar-generalize-diagnose`: Move the functionality of `scalar diagnose`
|
||||
into `git diagnose` and `git bugreport --diagnose`.
|
||||
|
||||
- 'scalar-add-fsmonitor: Enable the built-in FSMonitor in Scalar
|
||||
enlistments. At the end of this series, Scalar should be feature-complete
|
||||
from the perspective of a user.
|
||||
|
||||
Roughly speaking (and subject to change), the following series are needed to
|
||||
"finish" this initial version of Scalar:
|
||||
|
||||
- Move Scalar to toplevel: Move Scalar out of `contrib/` and into the root of
|
||||
`git`. This includes a variety of related updates, including:
|
||||
- building & installing Scalar in the Git root-level 'make [install]'.
|
||||
- builing & testing Scalar as part of CI.
|
||||
- moving and expanding test coverage of Scalar (including perf tests).
|
||||
- implementing 'scalar help'/'git help scalar' to display scalar
|
||||
documentation.
|
||||
|
||||
Finally, there are two additional patch series that exist in Microsoft's fork of
|
||||
Git, but there is no current plan to upstream them. There are some interesting
|
||||
ideas there, but the implementation is too specific to Azure Repos and/or VFS
|
||||
for Git to be of much help in general.
|
||||
|
||||
These still exist mainly because the GVFS protocol is what Azure Repos has
|
||||
instead of partial clone, while Git is focused on improving partial clone:
|
||||
|
||||
- `scalar-with-gvfs`: The primary purpose of this patch series is to support
|
||||
existing Scalar users whose repositories are hosted in Azure Repos (which does
|
||||
not support Git's partial clones, but supports its predecessor, the GVFS
|
||||
protocol, which is used by Scalar to emulate the partial clone).
|
||||
|
||||
Since the GVFS protocol will never be supported by core Git, this patch series
|
||||
will remain in Microsoft's fork of Git.
|
||||
|
||||
- `run-scalar-functional-tests`: The Scalar project developed a quite
|
||||
comprehensive set of integration tests (or, "Functional Tests"). They are the
|
||||
sole remaining part of the original C#-based Scalar project, and this patch
|
||||
adds a GitHub workflow that runs them all.
|
||||
|
||||
Since the tests partially depend on features that are only provided in the
|
||||
`scalar-with-gvfs` patch series, this patch cannot be upstreamed.
|
||||
|
||||
Reference in New Issue
Block a user