|
| 1 | +# Scalar - an opinionated repository management tool |
| 2 | + |
| 3 | +Scalar is an add-on to Git that helps users take advantage of advanced |
| 4 | +performance features in Git. Originally implemented in C# using .NET Core, |
| 5 | +based on the learnings from the VFS for Git project, most of the techniques |
| 6 | +developed 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 | + |
| 15 | +This directory contains the remaining parts of Scalar that are not (yet) in |
| 16 | +core Git. |
| 17 | + |
| 18 | +## Roadmap |
| 19 | + |
| 20 | +The idea is to populate this directory via incremental patch series and |
| 21 | +eventually move to a top-level directory next to `gitk-git/` and to `git-gui/`. The |
| 22 | +current 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 | + |
| 54 | +The following two patch series exist in Microsoft's fork of Git and are |
| 55 | +publicly available. There is no current plan to upstream them, not because I |
| 56 | +want to withhold these patches, but because I don't think the Git community is |
| 57 | +interested in these patches. |
| 58 | + |
| 59 | +There are some interesting ideas there, but the implementation is too specific |
| 60 | +to Azure Repos and/or VFS for Git to be of much help in general (and also: my |
| 61 | +colleagues tried to upstream some patches already and the enthusiasm for |
| 62 | +integrating things related to Azure Repos and VFS for Git can be summarized in |
| 63 | +very, very few words). |
| 64 | + |
| 65 | +These still exist mainly because the GVFS protocol is what Azure Repos has |
| 66 | +instead 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. |
0 commit comments