logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

scalar.1 (8192B)

    

  1. '\" t
  2. .\"     Title: scalar
  3. .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\"      Date: 2025-03-14
  6. .\"    Manual: Git Manual
  7. .\"    Source: Git 2.49.0
  8. .\"  Language: English
  9. .\"
  10. .TH "SCALAR" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el       .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. scalar \- A tool for managing large Git repositories
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. scalar clone [\-\-single\-branch] [\-\-branch <main\-branch>] [\-\-full\-clone]
  36.         [\-\-[no\-]src] <url> [<enlistment>]
  37. scalar list
  38. scalar register [<enlistment>]
  39. scalar unregister [<enlistment>]
  40. scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
  41. scalar reconfigure [ \-\-all | <enlistment> ]
  42. scalar diagnose [<enlistment>]
  43. scalar delete <enlistment>
  44. .fi
  45. .SH "DESCRIPTION"
  46. .sp
  47. 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\&.
  48. .sp
  49. An important Scalar concept is the enlistment: this is the top\-level directory of the project\&. It usually contains the subdirectory \fBsrc/\fR which is a Git worktree\&. This encourages the separation between tracked files (inside \fBsrc/\fR) and untracked files, such as build artifacts (outside \fBsrc/\fR)\&. When registering an existing Git worktree with Scalar whose name is not \fBsrc\fR, the enlistment will be identical to the worktree\&.
  50. .sp
  51. The \fBscalar\fR command implements various subcommands, and different options depending on the subcommand\&. With the exception of \fBclone\fR, \fBlist\fR and \fBreconfigure\fR \fB\-\-all\fR, all subcommands expect to be run in an enlistment\&.
  52. .sp
  53. The following options can be specified \fIbefore\fR the subcommand:
  54. .PP
  55. \-C <directory>
  56. .RS 4
  57. Before running the subcommand, change the working directory\&. This option imitates the same option of
  58. \fBgit\fR(1)\&.
  59. .RE
  60. .PP
  61. \-c <key>=<value>
  62. .RS 4
  63. For the duration of running the specified subcommand, configure this setting\&. This option imitates the same option of
  64. \fBgit\fR(1)\&.
  65. .RE
  66. .SH "COMMANDS"
  67. .SS "Clone"
  68. .PP
  69. clone [<options>] <url> [<enlistment>]
  70. .RS 4
  71. Clones the specified repository, similar to
  72. \fBgit-clone\fR(1)\&. By default, only commit and tree objects are cloned\&. Once finished, the worktree is located at
  73. \fI<enlistment>\fR\fB/src\fR\&.
  74. .sp
  75. The sparse\-checkout feature is enabled (except when run with
  76. \fB\-\-full\-clone\fR) and the only files present are those in the top\-level directory\&. Use
  77. \fBgit\fR
  78. \fBsparse\-checkout\fR
  79. \fBset\fR
  80. to expand the set of directories you want to see, or
  81. \fBgit\fR
  82. \fBsparse\-checkout\fR
  83. \fBdisable\fR
  84. to expand to all files (see
  85. \fBgit-sparse-checkout\fR(1)
  86. for more details)\&. You can explore the subdirectories outside your sparse\-checkout by using
  87. \fBgit\fR
  88. \fBls\-tree\fR
  89. \fBHEAD\fR[\fB:\fR\fI<directory>\fR]\&.
  90. .RE
  91. .PP
  92. \-b <name>, \-\-branch <name>
  93. .RS 4
  94. Instead of checking out the branch pointed to by the cloned repository\(cqs HEAD, check out the
  95. \fI<name>\fR
  96. branch instead\&.
  97. .RE
  98. .PP
  99. \-\-[no\-]single\-branch
  100. .RS 4
  101. Clone only the history leading to the tip of a single branch, either specified by the
  102. \fB\-\-branch\fR
  103. option or the primary branch remote\(cqs
  104. \fBHEAD\fR
  105. points at\&.
  106. .sp
  107. 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
  108. \fB\-\-single\-branch\fR
  109. clone was made, no remote\-tracking branch is created\&.
  110. .RE
  111. .PP
  112. \-\-[no\-]src
  113. .RS 4
  114. By default,
  115. \fBscalar\fR
  116. \fBclone\fR
  117. places the cloned repository within a
  118. \fI<entlistment>\fR\fB/src\fR
  119. directory\&. Use
  120. \fB\-\-no\-src\fR
  121. to place the cloned repository directly in the
  122. \fI<enlistment>\fR
  123. directory\&.
  124. .RE
  125. .PP
  126. \-\-[no\-]tags
  127. .RS 4
  128. By default,
  129. \fBscalar\fR
  130. \fBclone\fR
  131. will fetch the tag objects advertised by the remote and future
  132. \fBgit\fR
  133. \fBfetch\fR
  134. commands will do the same\&. Use
  135. \fB\-\-no\-tags\fR
  136. to avoid fetching tags in
  137. \fBscalar\fR
  138. \fBclone\fR
  139. and to configure the repository to avoid fetching tags in the future\&. To fetch tags after cloning with
  140. \fB\-\-no\-tags\fR, run
  141. \fBgit\fR
  142. \fBfetch\fR
  143. \fB\-\-tags\fR\&.
  144. .RE
  145. .PP
  146. \-\-[no\-]full\-clone
  147. .RS 4
  148. A sparse\-checkout is initialized by default\&. This behavior can be turned off via
  149. \fB\-\-full\-clone\fR\&.
  150. .RE
  151. .SS "List"
  152. .PP
  153. list
  154. .RS 4
  155. List enlistments that are currently registered by Scalar\&. This subcommand does not need to be run inside an enlistment\&.
  156. .RE
  157. .SS "Register"
  158. .PP
  159. register [<enlistment>]
  160. .RS 4
  161. Adds the enlistment\(cqs repository to the list of registered repositories and starts background maintenance\&. If
  162. \fI<enlistment>\fR
  163. is not provided, then the enlistment associated with the current working directory is registered\&.
  164. .sp
  165. Note: when this subcommand is called in a worktree that is called
  166. \fBsrc/\fR, its parent directory is considered to be the Scalar enlistment\&. If the worktree is
  167. \fInot\fR
  168. called
  169. \fBsrc/\fR, it itself will be considered to be the Scalar enlistment\&.
  170. .RE
  171. .SS "Unregister"
  172. .PP
  173. unregister [<enlistment>]
  174. .RS 4
  175. Remove the specified repository from the list of repositories registered with Scalar and stop the scheduled background maintenance\&.
  176. .RE
  177. .SS "Run"
  178. .PP
  179. scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
  180. .RS 4
  181. Run the given maintenance task (or all tasks, if
  182. \fBall\fR
  183. was specified)\&. Except for
  184. \fBall\fR
  185. and
  186. \fBconfig\fR, this subcommand simply hands off to
  187. \fBgit-maintenance\fR(1)
  188. (mapping
  189. \fBfetch\fR
  190. to
  191. \fBprefetch\fR
  192. and
  193. \fBpack\-files\fR
  194. to
  195. \fBincremental\-repack\fR)\&.
  196. .sp
  197. 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\&.
  198. .sp
  199. The
  200. \fBconfig\fR
  201. 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
  202. \fBscalar\fR
  203. \fBclone\fR
  204. automatically, explicit invocations of this task are rarely needed\&.
  205. .RE
  206. .SS "Reconfigure"
  207. .sp
  208. 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\&.
  209. .sp
  210. With the \fB\-\-all\fR option, all enlistments currently registered with Scalar will be reconfigured\&. Use this option after each Scalar upgrade\&.
  211. .SS "Diagnose"
  212. .PP
  213. diagnose [<enlistment>]
  214. .RS 4
  215. 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\&.
  216. .sp
  217. The output of this command is a \&.\fBzip\fR
  218. file that is written into a directory adjacent to the worktree in the
  219. \fBsrc\fR
  220. directory\&.
  221. .RE
  222. .SS "Delete"
  223. .PP
  224. delete <enlistment>
  225. .RS 4
  226. This subcommand lets you delete an existing Scalar enlistment from your local file system, unregistering the repository\&.
  227. .RE
  228. .SH "SEE ALSO"
  229. .sp
  230. \fBgit-clone\fR(1), \fBgit-maintenance\fR(1)\&.
  231. .SH "GIT"
  232. .sp
  233. Part of the \fBgit\fR(1) suite