]> git.ipfire.org Git - thirdparty/git.git/blame - contrib/scalar/README.md
clone: allow "--bare" with "-o"
[thirdparty/git.git] / contrib / scalar / README.md
CommitLineData
cd5a9ac0
JS
1# Scalar - an opinionated repository management tool
2
3Scalar is an add-on to Git that helps users take advantage of advanced
4performance features in Git. Originally implemented in C# using .NET Core,
5based on the learnings from the VFS for Git project, most of the techniques
6developed by the Scalar project have been integrated into core Git already:
7
8* partial clone,
9* commit graphs,
10* multi-pack index,
11* sparse checkout (cone mode),
12* scheduled background maintenance,
13* etc
14
15This directory contains the remaining parts of Scalar that are not (yet) in
16core Git.
17
18## Roadmap
19
20The idea is to populate this directory via incremental patch series and
21eventually move to a top-level directory next to `gitk-git/` and to `git-gui/`. The
22current plan involves the following patch series:
23
24- `scalar-the-beginning`: The initial patch series which sets up
25 `contrib/scalar/` and populates it with a minimal `scalar` command that
26 demonstrates the fundamental ideas.
27
28- `scalar-c-and-C`: The `scalar` command learns about two options that can be
29 specified before the command, `-c <key>=<value>` and `-C <directory>`.
30
31- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.
32
33- `scalar-and-builtin-fsmonitor`: The built-in FSMonitor is enabled in `scalar
34 register` and in `scalar clone`, for an enormous performance boost when
35 working in large worktrees. This patch series necessarily depends on Jeff
36 Hostetler's FSMonitor patch series to be integrated into Git.
37
38- `scalar-gentler-config-locking`: Scalar enlistments are registered in the
39 user's Git config. This usually does not represent any problem because it is
40 rare for a user to register an enlistment. However, in Scalar's functional
41 tests, Scalar enlistments are created galore, and in parallel, which can lead
42 to lock contention. This patch series works around that problem by re-trying
43 to lock the config file in a gentle fashion.
44
45- `scalar-extra-docs`: Add some extensive documentation that has been written
46 in the original Scalar project (all subject to discussion, of course).
47
48- `optionally-install-scalar`: Now that Scalar is feature (and documentation)
49 complete and is verified in CI builds, let's offer to install it.
50
51- `move-scalar-to-toplevel`: Now that Scalar is complete, let's move it next to
52 `gitk-git/` and to `git-gui/`, making it a top-level command.
53
54The following two patch series exist in Microsoft's fork of Git and are
55publicly available. There is no current plan to upstream them, not because I
56want to withhold these patches, but because I don't think the Git community is
57interested in these patches.
58
59There are some interesting ideas there, but the implementation is too specific
60to Azure Repos and/or VFS for Git to be of much help in general (and also: my
61colleagues tried to upstream some patches already and the enthusiasm for
62integrating things related to Azure Repos and VFS for Git can be summarized in
63very, very few words).
64
65These still exist mainly because the GVFS protocol is what Azure Repos has
66instead of partial clone, while Git is focused on improving partial clone:
67
68- `scalar-with-gvfs`: The primary purpose of this patch series is to support
69 existing Scalar users whose repositories are hosted in Azure Repos (which
70 does not support Git's partial clones, but supports its predecessor, the GVFS
71 protocol, which is used by Scalar to emulate the partial clone).
72
73 Since the GVFS protocol will never be supported by core Git, this patch
74 series will remain in Microsoft's fork of Git.
75
76- `run-scalar-functional-tests`: The Scalar project developed a quite
77 comprehensive set of integration tests (or, "Functional Tests"). They are the
78 sole remaining part of the original C#-based Scalar project, and this patch
79 adds a GitHub workflow that runs them all.
80
81 Since the tests partially depend on features that are only provided in the
82 `scalar-with-gvfs` patch series, this patch cannot be upstreamed.