| 1 | scalar(1) |
| 2 | ========= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | scalar - A tool for managing large Git repositories |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [verse] |
| 11 | scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] |
| 12 | [--[no-]src] [--[no-]tags] [--[no-]maintenance] <url> [<enlistment>] |
| 13 | scalar list |
| 14 | scalar register [--[no-]maintenance] [<enlistment>] |
| 15 | scalar unregister [<enlistment>] |
| 16 | scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] |
| 17 | scalar reconfigure [--maintenance=(enable|disable|keep)] [ --all | <enlistment> ] |
| 18 | scalar diagnose [<enlistment>] |
| 19 | scalar delete <enlistment> |
| 20 | |
| 21 | DESCRIPTION |
| 22 | ----------- |
| 23 | |
| 24 | Scalar is a repository management tool that optimizes Git for use in large |
| 25 | repositories. Scalar improves performance by configuring advanced Git settings, |
| 26 | maintaining repositories in the background, and helping to reduce data sent |
| 27 | across the network. |
| 28 | |
| 29 | An important Scalar concept is the enlistment: this is the top-level directory |
| 30 | of the project. It usually contains the subdirectory `src/` which is a Git |
| 31 | worktree. This encourages the separation between tracked files (inside `src/`) |
| 32 | and untracked files, such as build artifacts (outside `src/`). When registering |
| 33 | an existing Git worktree with Scalar whose name is not `src`, the enlistment |
| 34 | will be identical to the worktree. |
| 35 | |
| 36 | The `scalar` command implements various subcommands, and different options |
| 37 | depending on the subcommand. With the exception of `clone`, `list` and |
| 38 | `reconfigure --all`, all subcommands expect to be run in an enlistment. |
| 39 | |
| 40 | The following options can be specified _before_ the subcommand: |
| 41 | |
| 42 | -C <directory>:: |
| 43 | Before running the subcommand, change the working directory. This |
| 44 | option imitates the same option of linkgit:git[1]. |
| 45 | |
| 46 | -c <key>=<value>:: |
| 47 | For the duration of running the specified subcommand, configure this |
| 48 | setting. This option imitates the same option of linkgit:git[1]. |
| 49 | |
| 50 | COMMANDS |
| 51 | -------- |
| 52 | |
| 53 | Clone |
| 54 | ~~~~~ |
| 55 | |
| 56 | clone [<options>] <url> [<enlistment>]:: |
| 57 | Clones the specified repository, similar to linkgit:git-clone[1]. By |
| 58 | default, only commit and tree objects are cloned. Once finished, the |
| 59 | worktree is located at `<enlistment>/src`. |
| 60 | + |
| 61 | The sparse-checkout feature is enabled (except when run with `--full-clone`) |
| 62 | and the only files present are those in the top-level directory. Use |
| 63 | `git sparse-checkout set` to expand the set of directories you want to see, |
| 64 | or `git sparse-checkout disable` to expand to all files (see |
| 65 | linkgit:git-sparse-checkout[1] for more details). You can explore the |
| 66 | subdirectories outside your sparse-checkout by using `git ls-tree |
| 67 | HEAD[:<directory>]`. |
| 68 | |
| 69 | -b <name>:: |
| 70 | --branch <name>:: |
| 71 | Instead of checking out the branch pointed to by the cloned |
| 72 | repository's HEAD, check out the `<name>` branch instead. |
| 73 | |
| 74 | --single-branch:: |
| 75 | --no-single-branch:: |
| 76 | Clone only the history leading to the tip of a single branch, either |
| 77 | specified by the `--branch` option or the primary branch remote's |
| 78 | `HEAD` points at. |
| 79 | + |
| 80 | Further fetches into the resulting repository will only update the |
| 81 | remote-tracking branch for the branch this option was used for the initial |
| 82 | cloning. If the HEAD at the remote did not point at any branch when |
| 83 | `--single-branch` clone was made, no remote-tracking branch is created. |
| 84 | |
| 85 | --src:: |
| 86 | --no-src:: |
| 87 | By default, `scalar clone` places the cloned repository within a |
| 88 | `<entlistment>/src` directory. Use `--no-src` to place the cloned |
| 89 | repository directly in the `<enlistment>` directory. |
| 90 | |
| 91 | --tags:: |
| 92 | --no-tags:: |
| 93 | By default, `scalar clone` will fetch the tag objects advertised by |
| 94 | the remote and future `git fetch` commands will do the same. Use |
| 95 | `--no-tags` to avoid fetching tags in `scalar clone` and to configure |
| 96 | the repository to avoid fetching tags in the future. To fetch tags after |
| 97 | cloning with `--no-tags`, run `git fetch --tags`. |
| 98 | |
| 99 | --full-clone:: |
| 100 | --no-full-clone:: |
| 101 | A sparse-checkout is initialized by default. This behavior can be |
| 102 | turned off via `--full-clone`. |
| 103 | |
| 104 | --maintenance:: |
| 105 | --no-maintenance:: |
| 106 | By default, `scalar clone` configures the enlistment to use Git's |
| 107 | background maintenance feature. Use the `--no-maintenance` to skip |
| 108 | this configuration. |
| 109 | |
| 110 | List |
| 111 | ~~~~ |
| 112 | |
| 113 | list:: |
| 114 | List enlistments that are currently registered by Scalar. This |
| 115 | subcommand does not need to be run inside an enlistment. |
| 116 | |
| 117 | Register |
| 118 | ~~~~~~~~ |
| 119 | |
| 120 | register [<enlistment>]:: |
| 121 | Adds the enlistment's repository to the list of registered repositories |
| 122 | and starts background maintenance. If `<enlistment>` is not provided, |
| 123 | then the enlistment associated with the current working directory is |
| 124 | registered. |
| 125 | + |
| 126 | Note: when this subcommand is called in a worktree that is called `src/`, its |
| 127 | parent directory is considered to be the Scalar enlistment. If the worktree is |
| 128 | _not_ called `src/`, it itself will be considered to be the Scalar enlistment. |
| 129 | |
| 130 | --maintenance:: |
| 131 | --no-maintenance:: |
| 132 | By default, `scalar register` configures the enlistment to use Git's |
| 133 | background maintenance feature. Use the `--no-maintenance` to skip |
| 134 | this configuration. This does not disable any maintenance that may |
| 135 | already be enabled in other ways. |
| 136 | |
| 137 | Unregister |
| 138 | ~~~~~~~~~~ |
| 139 | |
| 140 | unregister [<enlistment>]:: |
| 141 | Remove the specified repository from the list of repositories |
| 142 | registered with Scalar and stop the scheduled background maintenance. |
| 143 | |
| 144 | Run |
| 145 | ~~~ |
| 146 | |
| 147 | scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]:: |
| 148 | Run the given maintenance task (or all tasks, if `all` was specified). |
| 149 | Except for `all` and `config`, this subcommand simply hands off to |
| 150 | linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and |
| 151 | `pack-files` to `incremental-repack`). |
| 152 | + |
| 153 | These tasks are run automatically as part of the scheduled maintenance, |
| 154 | as soon as the repository is registered with Scalar. It should therefore |
| 155 | not be necessary to run this subcommand manually. |
| 156 | + |
| 157 | The `config` task is specific to Scalar and configures all those |
| 158 | opinionated default settings that make Git work more efficiently with |
| 159 | large repositories. As this task is run as part of `scalar clone` |
| 160 | automatically, explicit invocations of this task are rarely needed. |
| 161 | |
| 162 | Reconfigure |
| 163 | ~~~~~~~~~~~ |
| 164 | |
| 165 | After a Scalar upgrade, or when the configuration of a Scalar enlistment |
| 166 | was somehow corrupted or changed by mistake, this subcommand allows to |
| 167 | reconfigure the enlistment. |
| 168 | |
| 169 | --all:: |
| 170 | When `--all` is specified, reconfigure all enlistments currently |
| 171 | registered with Scalar by the `scalar.repo` config key. Use this |
| 172 | option after each upgrade to get the latest features. |
| 173 | |
| 174 | --maintenance=(enable|disable|keep):: |
| 175 | By default, Scalar configures the enlistment to use Git's |
| 176 | background maintenance feature; this is the same as using the |
| 177 | `enable` value for this option. Use the `disable` value to |
| 178 | remove each considered enlistment from background maintenance. |
| 179 | Use `keep' to leave the background maintenance configuration |
| 180 | untouched for these repositories. |
| 181 | |
| 182 | Diagnose |
| 183 | ~~~~~~~~ |
| 184 | |
| 185 | diagnose [<enlistment>]:: |
| 186 | When reporting issues with Scalar, it is often helpful to provide the |
| 187 | information gathered by this command, including logs and certain |
| 188 | statistics describing the data shape of the current enlistment. |
| 189 | + |
| 190 | The output of this command is a `.zip` file that is written into |
| 191 | a directory adjacent to the worktree in the `src` directory. |
| 192 | |
| 193 | Delete |
| 194 | ~~~~~~ |
| 195 | |
| 196 | delete <enlistment>:: |
| 197 | This subcommand lets you delete an existing Scalar enlistment from your |
| 198 | local file system, unregistering the repository. |
| 199 | |
| 200 | RECOMMENDED CONFIG VALUES |
| 201 | ------------------------- |
| 202 | |
| 203 | As part of both `scalar clone` and `scalar register`, certain Git config |
| 204 | values are set to optimize for large repositories or cross-platform support. |
| 205 | These options are updated in new Git versions according to the best known |
| 206 | advice for large repositories, and users can get the latest recommendations |
| 207 | by running `scalar reconfigure [--all]`. |
| 208 | |
| 209 | This section lists justifications for the config values that are set in the |
| 210 | latest version. |
| 211 | |
| 212 | am.keepCR=true:: |
| 213 | This setting is important for cross-platform development across Windows |
| 214 | and non-Windows platforms and keeping carriage return (`\r`) characters |
| 215 | in certain workflows. |
| 216 | |
| 217 | commitGraph.changedPaths=true:: |
| 218 | This setting helps the background maintenance steps that compute the |
| 219 | serialized commit-graph to also store changed-path Bloom filters. This |
| 220 | accelerates file history commands and allows users to automatically |
| 221 | benefit without running a foreground command. |
| 222 | |
| 223 | commitGraph.generationVersion=1:: |
| 224 | While the preferred version is 2 for performance reasons, existing users |
| 225 | that had version 1 by default will need special care in upgrading to |
| 226 | version 2. This is likely to change in the future as the upgrade story |
| 227 | solidifies. |
| 228 | |
| 229 | core.autoCRLF=false:: |
| 230 | This removes the transformation of worktree files to add CRLF line |
| 231 | endings when only LF line endings exist. This is removed for performance |
| 232 | reasons. Repositories that use tools that care about CRLF line endings |
| 233 | should commit the necessary files with those line endings instead. |
| 234 | |
| 235 | core.logAllRefUpdates=true:: |
| 236 | This enables the reflog on all branches. While this is a performance |
| 237 | cost for large repositories, it is frequently an important data source |
| 238 | for users to get out of bad situations or to seek support from experts. |
| 239 | |
| 240 | core.safeCRLF=false:: |
| 241 | Similar to `core.autoCRLF=false`, this disables checks around whether |
| 242 | the CRLF conversion is reversible. This is a performance improvement, |
| 243 | but can be dangerous if `core.autoCRLF` is reenabled by the user. |
| 244 | |
| 245 | credential.https://dev.azure.com.useHttpPath=true:: |
| 246 | This setting enables the `credential.useHttpPath` feature only for web |
| 247 | URLs for Azure DevOps. This is important for users interacting with that |
| 248 | service using multiple organizations and thus multiple credential |
| 249 | tokens. |
| 250 | |
| 251 | feature.experimental=false:: |
| 252 | This disables the "experimental" optimizations grouped under this |
| 253 | feature config. The expectation is that all valuable optimizations are |
| 254 | also set explicitly by Scalar config, and any differences are |
| 255 | intentional. Notable differences include several bitmap-related config |
| 256 | options which are disabled for client-focused Scalar repos. |
| 257 | |
| 258 | feature.manyFiles=false:: |
| 259 | This disables the "many files" optimizations grouped under this feature |
| 260 | config. The expectation is that all valuable optimizations are also set |
| 261 | explicitly by Scalar config, and any differences are intentional. |
| 262 | |
| 263 | fetch.showForcedUpdates=false:: |
| 264 | This disables the check at the end of `git fetch` that notifies the user |
| 265 | if the ref update was a forced update (one where the previous position |
| 266 | is not reachable from the latest position). This check can be very |
| 267 | expensive in large repositories, so is disabled and replaced with an |
| 268 | advice message. Set `advice.fetchShowForcedUpdates=false` to disable |
| 269 | this advice message. |
| 270 | |
| 271 | fetch.unpackLimit=1:: |
| 272 | This setting prevents Git from unpacking packfiles into loose objects |
| 273 | as they are downloaded from the server. The default limit of 100 was |
| 274 | intended as a way to prevent performance issues from too many packfiles, |
| 275 | but Scalar uses background maintenance to group packfiles and cover them |
| 276 | with a multi-pack-index, removing this issue. |
| 277 | |
| 278 | fetch.writeCommitGraph=false:: |
| 279 | This config setting was created to help users automatically update their |
| 280 | commit-graph files as they perform fetches. However, this takes time |
| 281 | from foreground fetches and pulls and Scalar uses background maintenance |
| 282 | for this function instead. |
| 283 | |
| 284 | gc.auto=0:: |
| 285 | This disables automatic garbage collection, since Scalar uses background |
| 286 | maintenance to keep the repository data in good shape. |
| 287 | |
| 288 | gui.GCWarning=false:: |
| 289 | Since Scalar disables garbage collection by setting `gc.auto=0`, the |
| 290 | `git-gui` tool may start to warn about this setting. Disable this |
| 291 | warning as Scalar's background maintenance configuration makes the |
| 292 | warning irrelevant. |
| 293 | |
| 294 | index.skipHash=true:: |
| 295 | Disable computing the hash of the index contents as it is being written. |
| 296 | This assists with performance, especially for large index files. |
| 297 | |
| 298 | index.threads=true:: |
| 299 | This tells Git to automatically detect how many threads it should use |
| 300 | when reading the index due to the default value of `core.preloadIndex`, |
| 301 | which enables parallel index reads. This explicit setting also enables |
| 302 | `index.recordOffsetTable=true` to speed up parallel index reads. |
| 303 | |
| 304 | index.version=4:: |
| 305 | This index version adds compression to the path names, reducing the size |
| 306 | of the index in a significant way for large repos. This is an important |
| 307 | performance boost. |
| 308 | |
| 309 | log.excludeDecoration=refs/prefetch/*:: |
| 310 | Since Scalar enables background maintenance with the `incremental` |
| 311 | strategy, this setting avoids polluting `git log` output with refs |
| 312 | stored by the background prefetch operations. |
| 313 | |
| 314 | merge.renames=true:: |
| 315 | When computing merges in large repos, it is particularly important to |
| 316 | detect renames to maximize the potential for a result that will validate |
| 317 | correctly. Users performing merges locally are more likely to be doing |
| 318 | so because a server-side merge (via pull request or similar) resulted in |
| 319 | conflicts. While this is the default setting, it is set specifically to |
| 320 | override a potential change to `diff.renames` which a user may set for |
| 321 | performance reasons. |
| 322 | |
| 323 | merge.stat=false:: |
| 324 | This disables a diff output after computing a merge. This improves |
| 325 | performance of `git merge` for large repos while reducing noisy output. |
| 326 | |
| 327 | pack.useBitmaps=false:: |
| 328 | This disables the use of `.bitmap` files attached to packfiles. Bitmap |
| 329 | files are optimized for server-side use, not client-side use. Scalar |
| 330 | disables this to avoid some performance issues that can occur if a user |
| 331 | accidentally creates `.bitmap` files. |
| 332 | |
| 333 | pack.usePathWalk=true:: |
| 334 | This enables the `--path-walk` option to `git pack-objects` by default. |
| 335 | This can accelerate the computation and compression of packfiles created |
| 336 | by `git push` and other repack operations. |
| 337 | |
| 338 | receive.autoGC=false:: |
| 339 | Similar to `gc.auto`, this setting is disabled in preference of |
| 340 | background maintenance. |
| 341 | |
| 342 | status.aheadBehind=false:: |
| 343 | This disables the ahead/behind calculation that would normally happen |
| 344 | during a `git status` command. This information is frequently ignored by |
| 345 | users but can be expensive to calculate in large repos that receive |
| 346 | thousands of commits per day. The calculation is replaced with an advice |
| 347 | message that can be disabled by disabling the `advice.statusAheadBehind` |
| 348 | config. |
| 349 | |
| 350 | The following settings are different based on which platform is in use: |
| 351 | |
| 352 | core.untrackedCache=(true|false):: |
| 353 | The untracked cache feature is important for performance benefits on |
| 354 | large repositories, but has demonstrated some bugs on Windows |
| 355 | filesystems. Thus, this is set for other platforms but disabled on |
| 356 | Windows. |
| 357 | |
| 358 | http.sslBackend=schannel:: |
| 359 | On Windows, the `openssl` backend has some issues with certain types of |
| 360 | remote providers and certificate types. Override the default setting to |
| 361 | avoid these common problems. |
| 362 | |
| 363 | |
| 364 | SEE ALSO |
| 365 | -------- |
| 366 | linkgit:git-clone[1], linkgit:git-maintenance[1]. |
| 367 | |
| 368 | GIT |
| 369 | --- |
| 370 | Part of the linkgit:git[1] suite |