contrib/scalar/scalar.txt

   1 scalar(1)
   2 =========
   3
   4 NAME
   5 ----
   6 scalar - an opinionated repository management tool
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
  12 scalar list
  13 scalar register [<enlistment>]
  14 scalar unregister [<enlistment>]
  15 scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
  16 scalar reconfigure [ --all | <enlistment> ]
  17 scalar delete <enlistment>
  18
  19 DESCRIPTION
  20 -----------
  21
  22 Scalar is an opinionated repository management tool. By creating new
  23 repositories or registering existing repositories with Scalar, your Git
  24 experience will speed up. Scalar sets advanced Git config settings,
  25 maintains your repositories in the background, and helps reduce data sent
  26 across the network.
  27
  28 An important Scalar concept is the enlistment: this is the top-level directory
  29 of the project. It usually contains the subdirectory `src/` which is a Git
  30 worktree. This encourages the separation between tracked files (inside `src/`)
  31 and untracked files, such as build artifacts (outside `src/`). When registering
  32 an existing Git worktree with Scalar whose name is not `src`, the enlistment
  33 will be identical to the worktree.
  34
  35 The `scalar` command implements various subcommands, and different options
  36 depending on the subcommand. With the exception of `clone`, `list` and
  37 `reconfigure --all`, all subcommands expect to be run in an enlistment.
  38
  39 COMMANDS
  40 --------
  41
  42 Clone
  43 ~~~~~
  44
  45 clone [<options>] <url> [<enlistment>]::
  46         Clones the specified repository, similar to linkgit:git-clone[1]. By
  47         default, only commit and tree objects are cloned. Once finished, the
  48         worktree is located at `<enlistment>/src`.
  49 +
  50 The sparse-checkout feature is enabled (except when run with `--full-clone`)
  51 and the only files present are those in the top-level directory. Use
  52 `git sparse-checkout set` to expand the set of directories you want to see,
  53 or `git sparse-checkout disable` to expand to all files (see
  54 linkgit:git-sparse-checkout[1] for more details). You can explore the
  55 subdirectories outside your sparse-checkout by using `git ls-tree
  56 HEAD[:<directory>]`.
  57
  58 -b <name>::
  59 --branch <name>::
  60         Instead of checking out the branch pointed to by the cloned
  61         repository's HEAD, check out the `<name>` branch instead.
  62
  63 --[no-]single-branch::
  64         Clone only the history leading to the tip of a single branch, either
  65         specified by the `--branch` option or the primary branch remote's
  66         `HEAD` points at.
  67 +
  68 Further fetches into the resulting repository will only update the
  69 remote-tracking branch for the branch this option was used for the initial
  70 cloning. If the HEAD at the remote did not point at any branch when
  71 `--single-branch` clone was made, no remote-tracking branch is created.
  72
  73 --[no-]full-clone::
  74         A sparse-checkout is initialized by default. This behavior can be
  75         turned off via `--full-clone`.
  76
  77 List
  78 ~~~~
  79
  80 list::
  81         List enlistments that are currently registered by Scalar. This
  82         subcommand does not need to be run inside an enlistment.
  83
  84 Register
  85 ~~~~~~~~
  86
  87 register [<enlistment>]::
  88         Adds the enlistment's repository to the list of registered repositories
  89         and starts background maintenance. If `<enlistment>` is not provided,
  90         then the enlistment associated with the current working directory is
  91         registered.
  92 +
  93 Note: when this subcommand is called in a worktree that is called `src/`, its
  94 parent directory is considered to be the Scalar enlistment. If the worktree is
  95 _not_ called `src/`, it itself will be considered to be the Scalar enlistment.
  96
  97 Unregister
  98 ~~~~~~~~~~
  99
 100 unregister [<enlistment>]::
 101         Remove the specified repository from the list of repositories
 102         registered with Scalar and stop the scheduled background maintenance.
 103
 104 Run
 105 ~~~
 106
 107 scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]::
 108         Run the given maintenance task (or all tasks, if `all` was specified).
 109         Except for `all` and `config`, this subcommand simply hands off to
 110         linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and
 111         `pack-files` to `incremental-repack`).
 112 +
 113 These tasks are run automatically as part of the scheduled maintenance,
 114 as soon as the repository is registered with Scalar. It should therefore
 115 not be necessary to run this subcommand manually.
 116 +
 117 The `config` task is specific to Scalar and configures all those
 118 opinionated default settings that make Git work more efficiently with
 119 large repositories. As this task is run as part of `scalar clone`
 120 automatically, explicit invocations of this task are rarely needed.
 121
 122 Reconfigure
 123 ~~~~~~~~~~~
 124
 125 After a Scalar upgrade, or when the configuration of a Scalar enlistment
 126 was somehow corrupted or changed by mistake, this subcommand allows to
 127 reconfigure the enlistment.
 128
 129 With the `--all` option, all enlistments currently registered with Scalar
 130 will be reconfigured. Use this option after each Scalar upgrade.
 131
 132 Delete
 133 ~~~~~~
 134
 135 delete <enlistment>::
 136         This subcommand lets you delete an existing Scalar enlistment from your
 137         local file system, unregistering the repository.
 138
 139 SEE ALSO
 140 --------
 141 linkgit:git-clone[1], linkgit:git-maintenance[1].
 142
 143 Scalar
 144 ---
 145 Associated with the linkgit:git[1] suite