]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/scalar.txt
Merge branch 'jk/clone-allow-bare-and-o-together'
[thirdparty/git.git] / Documentation / scalar.txt
CommitLineData
829fe56c
JS
1scalar(1)
2=========
3
4NAME
5----
f22c95db 6scalar - A tool for managing large Git repositories
829fe56c
JS
7
8SYNOPSIS
9--------
10[verse]
4368e40b 11scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
2b710457 12scalar list
d0feac4e 13scalar register [<enlistment>]
c76a53eb 14scalar unregister [<enlistment>]
7020c88c 15scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
45826760 16scalar reconfigure [ --all | <enlistment> ]
aa5c79a3 17scalar diagnose [<enlistment>]
d85ada7c 18scalar delete <enlistment>
829fe56c
JS
19
20DESCRIPTION
21-----------
22
f22c95db
VD
23Scalar is a repository management tool that optimizes Git for use in large
24repositories. Scalar improves performance by configuring advanced Git settings,
25maintaining repositories in the background, and helping to reduce data sent
829fe56c
JS
26across the network.
27
28An important Scalar concept is the enlistment: this is the top-level directory
29of the project. It usually contains the subdirectory `src/` which is a Git
30worktree. This encourages the separation between tracked files (inside `src/`)
31and untracked files, such as build artifacts (outside `src/`). When registering
32an existing Git worktree with Scalar whose name is not `src`, the enlistment
33will be identical to the worktree.
34
35The `scalar` command implements various subcommands, and different options
45826760
JS
36depending on the subcommand. With the exception of `clone`, `list` and
37`reconfigure --all`, all subcommands expect to be run in an enlistment.
829fe56c 38
2ae8eb5d
JS
39The following options can be specified _before_ the subcommand:
40
41-C <directory>::
42 Before running the subcommand, change the working directory. This
43 option imitates the same option of linkgit:git[1].
44
45-c <key>=<value>::
46 For the duration of running the specified subcommand, configure this
47 setting. This option imitates the same option of linkgit:git[1].
48
d0feac4e
DS
49COMMANDS
50--------
51
546f822d
JS
52Clone
53~~~~~
54
55clone [<options>] <url> [<enlistment>]::
56 Clones the specified repository, similar to linkgit:git-clone[1]. By
57 default, only commit and tree objects are cloned. Once finished, the
58 worktree is located at `<enlistment>/src`.
59+
60The sparse-checkout feature is enabled (except when run with `--full-clone`)
61and the only files present are those in the top-level directory. Use
62`git sparse-checkout set` to expand the set of directories you want to see,
63or `git sparse-checkout disable` to expand to all files (see
64linkgit:git-sparse-checkout[1] for more details). You can explore the
65subdirectories outside your sparse-checkout by using `git ls-tree
66HEAD[:<directory>]`.
67
68-b <name>::
69--branch <name>::
70 Instead of checking out the branch pointed to by the cloned
71 repository's HEAD, check out the `<name>` branch instead.
72
4368e40b
JS
73--[no-]single-branch::
74 Clone only the history leading to the tip of a single branch, either
75 specified by the `--branch` option or the primary branch remote's
76 `HEAD` points at.
77+
78Further fetches into the resulting repository will only update the
79remote-tracking branch for the branch this option was used for the initial
80cloning. If the HEAD at the remote did not point at any branch when
81`--single-branch` clone was made, no remote-tracking branch is created.
82
546f822d
JS
83--[no-]full-clone::
84 A sparse-checkout is initialized by default. This behavior can be
85 turned off via `--full-clone`.
86
2b710457
DS
87List
88~~~~
89
90list::
91 List enlistments that are currently registered by Scalar. This
92 subcommand does not need to be run inside an enlistment.
93
d0feac4e
DS
94Register
95~~~~~~~~
96
97register [<enlistment>]::
98 Adds the enlistment's repository to the list of registered repositories
99 and starts background maintenance. If `<enlistment>` is not provided,
100 then the enlistment associated with the current working directory is
101 registered.
102+
103Note: when this subcommand is called in a worktree that is called `src/`, its
104parent directory is considered to be the Scalar enlistment. If the worktree is
105_not_ called `src/`, it itself will be considered to be the Scalar enlistment.
106
c76a53eb
DS
107Unregister
108~~~~~~~~~~
109
110unregister [<enlistment>]::
111 Remove the specified repository from the list of repositories
112 registered with Scalar and stop the scheduled background maintenance.
113
7020c88c
DS
114Run
115~~~
116
117scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]::
118 Run the given maintenance task (or all tasks, if `all` was specified).
119 Except for `all` and `config`, this subcommand simply hands off to
120 linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and
121 `pack-files` to `incremental-repack`).
122+
123These tasks are run automatically as part of the scheduled maintenance,
124as soon as the repository is registered with Scalar. It should therefore
125not be necessary to run this subcommand manually.
126+
127The `config` task is specific to Scalar and configures all those
128opinionated default settings that make Git work more efficiently with
129large repositories. As this task is run as part of `scalar clone`
130automatically, explicit invocations of this task are rarely needed.
131
cb59d55e
JS
132Reconfigure
133~~~~~~~~~~~
134
135After a Scalar upgrade, or when the configuration of a Scalar enlistment
136was somehow corrupted or changed by mistake, this subcommand allows to
137reconfigure the enlistment.
138
45826760
JS
139With the `--all` option, all enlistments currently registered with Scalar
140will be reconfigured. Use this option after each Scalar upgrade.
141
aa5c79a3
JS
142Diagnose
143~~~~~~~~
144
145diagnose [<enlistment>]::
146 When reporting issues with Scalar, it is often helpful to provide the
147 information gathered by this command, including logs and certain
148 statistics describing the data shape of the current enlistment.
149+
150The output of this command is a `.zip` file that is written into
151a directory adjacent to the worktree in the `src` directory.
152
d85ada7c
MJC
153Delete
154~~~~~~
155
156delete <enlistment>::
157 This subcommand lets you delete an existing Scalar enlistment from your
158 local file system, unregistering the repository.
159
829fe56c
JS
160SEE ALSO
161--------
546f822d 162linkgit:git-clone[1], linkgit:git-maintenance[1].
829fe56c 163
b6faef39 164GIT
829fe56c 165---
b6faef39 166Part of the linkgit:git[1] suite