Skip to content

Upstreaming the Scalar command #1005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dscho wants to merge 15 commits into from
Closed

Upstreaming the Scalar command #1005

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
3a2e282
scalar: add a README with a roadmap
dscho Nov 16, 2021
50160d6
scalar: create a rudimentary executable
dscho Apr 10, 2021
74cd641
scalar: start documenting the command
dscho May 3, 2021
37231a4
scalar: create test infrastructure
dscho Apr 14, 2021
4439ab4
scalar: 'register' sets recommended config and starts maintenance
derrickstolee Apr 12, 2021
3760560
scalar: 'unregister' stops background maintenance
derrickstolee Apr 12, 2021
c865e89
scalar: let 'unregister' handle a deleted enlistment directory gracef…
dscho May 14, 2021
3f8b0ab
scalar: implement 'scalar list'
derrickstolee Apr 12, 2021
60659c4
scalar: implement the `clone` subcommand
dscho Apr 12, 2021
45aca84
scalar: teach 'clone' to support the --single-branch option
dscho Apr 16, 2021
15e649a
scalar: implement the `run` command
derrickstolee Apr 14, 2021
2a3fb40
scalar: allow reconfiguring an existing enlistment
dscho May 27, 2021
efd808a
scalar: teach 'reconfigure' to optionally handle all registered enlis…
dscho May 27, 2021
8b69462
scalar: implement the `delete` command
mjcheetham May 12, 2021
b5f416d
scalar: implement the `version` command
dscho May 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2456,6 +2456,11 @@ OBJECTS += $(FUZZ_OBJS)
ifndef NO_CURL
OBJECTS += http.o http-walker.o remote-curl.o
endif

SCALAR_SOURCES := contrib/scalar/scalar.c
SCALAR_OBJECTS := $(SCALAR_SOURCES:c=o)
OBJECTS += $(SCALAR_OBJECTS)

.PHONY: objects
objects: $(OBJECTS)

Expand Down Expand Up @@ -2589,6 +2594,10 @@ $(REMOTE_CURL_PRIMARY): remote-curl.o http.o http-walker.o GIT-LDFLAGS $(GITLIBS
$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) \
$(CURL_LIBCURL) $(EXPAT_LIBEXPAT) $(LIBS)

contrib/scalar/scalar$X: $(SCALAR_OBJECTS) GIT-LDFLAGS $(GITLIBS)
$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) \
$(filter %.o,$^) $(LIBS)

$(LIB_FILE): $(LIB_OBJS)
$(QUIET_AR)$(RM) $@ && $(AR) $(ARFLAGS) $@ $^

Expand Down
2 changes: 2 additions & 0 deletions contrib/scalar/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/*.exe
/scalar
45 changes: 45 additions & 0 deletions contrib/scalar/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir
Copy link

@gitgitgadget gitgitgadget bot Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Ævar Arnfjörð Bjarmason wrote (reply to this):


On Mon, Aug 30 2021, Johannes Schindelin via GitGitGadget wrote:

> To test the Scalar command, create a test script in contrib/scalar/t
> that is executed as `make -C contrib/scalar test`. Since Scalar has no
> meaningful capabilities yet, the only test is rather simple. We will add
> more tests in subsequent commits that introduce corresponding, new
> functionality.

As a comment on 01..03/15: I'd really prefer if we stop using this
pattern of sub-Makefile, the dependencies are a pain to manage, and we
end up copy/pasting large sets of functionality.

That would mean just adding the build of this command to the top-level
Makefile behind some "CONTRIB_SCALAR" flag or whatever, but I find that
much cleaner than....

> @@ -21,7 +22,7 @@ include ../../config.mak.uname
>  TARGETS = scalar$(X) scalar.o
>  GITLIBS = ../../common-main.o ../../libgit.a ../../xdiff/lib.a
>  
> -all: scalar$X
> +all: scalar$X ../../bin-wrappers/scalar
>  
> [...]
> +../../bin-wrappers/scalar: ../../wrap-for-bin.sh Makefile
> [...]
>  scalar.html: | scalar.1 # prevent them from trying to build `doc.dep` in parallel

...things like this, which refer to assets built by other Makefiles, and
need to plaster over the dependency issues...

> +++ b/contrib/scalar/t/Makefile
> @@ -0,0 +1,78 @@
> +# Run scalar tests
> +#
> +# Copyright (c) 2005,2021 Junio C Hamano, Johannes Schindelin
> +#
> +
> +-include ../../../config.mak.autogen
> +-include ../../../config.mak
> +
> +SHELL_PATH ?= $(SHELL)
> +PERL_PATH ?= /usr/bin/perl
> +RM ?= rm -f
> +PROVE ?= prove
> +DEFAULT_TEST_TARGET ?= test
> +TEST_LINT ?= test-lint
> +
> +ifdef TEST_OUTPUT_DIRECTORY
> +TEST_RESULTS_DIRECTORY = $(TEST_OUTPUT_DIRECTORY)/test-results
> +else
> +TEST_RESULTS_DIRECTORY = ../../../t/test-results
> +endif
> +
> +# Shell quote;
> +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
> +PERL_PATH_SQ = $(subst ','\'',$(PERL_PATH))
> +TEST_RESULTS_DIRECTORY_SQ = $(subst ','\'',$(TEST_RESULTS_DIRECTORY))
> +
> +T = $(sort $(wildcard t[0-9][0-9][0-9][0-9]-*.sh))
> +
> +all: $(DEFAULT_TEST_TARGET)
> +
> +test: $(TEST_LINT)
> +	$(MAKE) aggregate-results-and-cleanup
> +
> +prove: $(TEST_LINT)
> +	@echo "*** prove ***"; GIT_CONFIG=.git/config $(PROVE) --exec '$(SHELL_PATH_SQ)' $(GIT_PROVE_OPTS) $(T) :: $(GIT_TEST_OPTS)
> +	$(MAKE) clean-except-prove-cache
> +
> +$(T):
> +	@echo "*** $@ ***"; GIT_CONFIG=.git/config '$(SHELL_PATH_SQ)' $@ $(GIT_TEST_OPTS)
> +
> +clean-except-prove-cache:
> +	$(RM) -r 'trash directory'.* '$(TEST_RESULTS_DIRECTORY_SQ)'
> +	$(RM) -r valgrind/bin
> +
> +clean: clean-except-prove-cache
> +	$(RM) .prove
> +
> +test-lint: test-lint-duplicates test-lint-executable test-lint-shell-syntax
> +
> +test-lint-duplicates:
> +	@dups=`echo $(T) | tr ' ' '\n' | sed 's/-.*//' | sort | uniq -d` && \
> +		test -z "$$dups" || { \
> +		echo >&2 "duplicate test numbers:" $$dups; exit 1; }
> +
> +test-lint-executable:
> +	@bad=`for i in $(T); do test -x "$$i" || echo $$i; done` && \
> +		test -z "$$bad" || { \
> +		echo >&2 "non-executable tests:" $$bad; exit 1; }
> +
> +test-lint-shell-syntax:
> +	@'$(PERL_PATH_SQ)' ../../../t/check-non-portable-shell.pl $(T)
> +
> +aggregate-results-and-cleanup: $(T)
> +	$(MAKE) aggregate-results
> +	$(MAKE) clean
> +
> +aggregate-results:
> +	for f in '$(TEST_RESULTS_DIRECTORY_SQ)'/t*-*.counts; do \
> +		echo "$$f"; \
> +	done | '$(SHELL_PATH_SQ)' ../../../t/aggregate-results.sh
> +
> +valgrind:
> +	$(MAKE) GIT_TEST_OPTS="$(GIT_TEST_OPTS) --valgrind"
> +
> +test-results:
> +	mkdir -p test-results
> +
> +.PHONY: $(T) aggregate-results clean valgrind

...and this entire copy/pasting & adjusting of t/Makefile.

Copy link

@gitgitgadget gitgitgadget bot Nov 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Ævar Arnfjörð Bjarmason wrote (reply to this):


On Fri, Nov 19 2021, Johannes Schindelin via GitGitGadget wrote:

> From: Johannes Schindelin <[email protected]>
> [...]
> +-include ../../../config.mak.autogen
> +-include ../../../config.mak
> +
> +SHELL_PATH ?= $(SHELL)
> +PERL_PATH ?= /usr/bin/perl
> +RM ?= rm -f
> +PROVE ?= prove
> +DEFAULT_TEST_TARGET ?= test
> +TEST_LINT ?= test-lint
> +
> +ifdef TEST_OUTPUT_DIRECTORY
> +TEST_RESULTS_DIRECTORY = $(TEST_OUTPUT_DIRECTORY)/test-results
> +else
> +TEST_RESULTS_DIRECTORY = ../../../t/test-results
> +endif

So here we'll inject our output into t/test-results[...]

> +T = $(sort $(wildcard t[0-9][0-9][0-9][0-9]-*.sh))

...end up with a $(T) with just the one scalar test...

> +test-lint-duplicates:
> +	@dups=`echo $(T) | tr ' ' '\n' | sed 's/-.*//' | sort | uniq -d` && \
> +		test -z "$$dups" || { \
> +		echo >&2 "duplicate test numbers:" $$dups; exit 1; }
> +

...so I *think* (but haven't checked) that print-test-failures.sh will
work with the later CI integration, but both t/Makefile & this one
assume in some ways that test numbers are unique, this now lives in the
same namespace, but neither check the two for conflicts.

We only have the one t9099 test here, so unless we add another one in
the top-level t/ that should be OK, but is there any reason to carry
this at all? It seems pointless given the above.

I think to make this meaningful we'd need to teach t/Makefile to have a
T_ALL variable or something, derived from its T, and have that wildcard
the scalar tests and other contrib tests and check them for namespacing
conflicts.

> +test-results:
> +	mkdir -p test-results
> +

This target seems to be unused, don't we always use the top-level
t/test-results? This seems to be copy/pasting also dead code from
contrib/subtree/t/Makefile.

QUIET_SUBDIR1 =

ifneq ($(findstring s,$(MAKEFLAGS)),s)
ifndef V
QUIET_GEN = @echo ' ' GEN $@;
QUIET_SUBDIR0 = +@subdir=
QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
$(MAKE) $(PRINT_DIR) -C $$subdir
else
export V
endif
endif

all:

include ../../config.mak.uname
-include ../../config.mak.autogen
-include ../../config.mak

TARGETS = scalar$(X) scalar.o
GITLIBS = ../../common-main.o ../../libgit.a ../../xdiff/lib.a

all: scalar$(X) ../../bin-wrappers/scalar

$(GITLIBS):
$(QUIET_SUBDIR0)../.. $(QUIET_SUBDIR1) $(subst ../../,,$@)

$(TARGETS): $(GITLIBS) scalar.c
$(QUIET_SUBDIR0)../.. $(QUIET_SUBDIR1) $(patsubst %,contrib/scalar/%,$@)

clean:
$(RM) $(TARGETS) ../../bin-wrappers/scalar

../../bin-wrappers/scalar: ../../wrap-for-bin.sh Makefile
@mkdir -p ../../bin-wrappers
$(QUIET_GEN)sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \
-e 's|@@BUILD_DIR@@|$(shell cd ../.. && pwd)|' \
-e 's|@@PROG@@|contrib/scalar/scalar$(X)|' < $< > $@ && \
chmod +x $@

test: all
$(MAKE) -C t

.PHONY: $(GITLIBS) all clean test FORCE
82 changes: 82 additions & 0 deletions contrib/scalar/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Scalar - an opinionated repository management tool
Copy link

@gitgitgadget gitgitgadget bot Nov 17, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 11/17/2021 9:19 AM, Johannes Schindelin via GitGitGadget wrote:
> From: Johannes Schindelin <[email protected]>
> 
> The Scalar command will be contributed incrementally, over a bunch of
> patch series. Let's document what Scalar is about, and then describe the
> patch series that are planned.
> 
> Signed-off-by: Johannes Schindelin <[email protected]>
> ---
>  contrib/scalar/README.md | 71 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 71 insertions(+)
>  create mode 100644 contrib/scalar/README.md
> 
> diff --git a/contrib/scalar/README.md b/contrib/scalar/README.md
> new file mode 100644
> index 00000000000..7898a683ba5
> --- /dev/null
> +++ b/contrib/scalar/README.md
> @@ -0,0 +1,71 @@
> +# Scalar - an opinionated repository management tool
> +
> +Scalar is an add-on to Git, helping Git scale to very large repositories and
> +worktrees.

I would rephrase this as "Scalar is an add-on to Git that helps users take
advantage of advanced performance features in Git."

Git scales just fine, only it helps to enable some features that are off
by default.

> Originally implemented in C# using .NET Core, based on the learnings
> +from the VFS for Git project, most of the techniques developed by the Scalar
> +project have been integrated into core Git already:
> +
> +* partial clone,
> +* commit graphs,
> +* multi-pack index,
> +* sparse checkout (cone mode),
> +* scheduled background maintenance,
> +* etc
> +
> +This directory contains the remaining parts of Scalar that are not (yet) in
> +core Git.
> +
> +## Roadmap
> +
> +The idea is to populate this directory via incremental patch series and
> +eventually move to a top-level directory next to `gitk-git/` and to `git-gui/`. The
> +current plan involves the following patch series:
> +
> +- `scalar-the-beginning`: The initial patch series which sets up
> +  `contrib/scalar/` and populates it with a minimal `scalar` command that
> +  demonstrates the fundamental ideas.
> +
> +- `scalar-c-and-C`: The `scalar` command learns about two options that can be
> +  specified before the command, `-c <key>=<value>` and `-C <directory>`.
> +
> +- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.
> +
> +- `scalar-and-builtin-fsmonitor`: The built-in FSMonitor is enabled in `scalar
> +  init` and in `scalar clone`, for an enormous performance boost when working
> +  in large worktrees. This patch series necessarily depends on Jeff Hostetler's
> +  FSMonitor patch series to be integrated into Git.

You say 'scalar init' but do you mean 'scalar register'?

> +- `scalar-gentler-config-locking`: Scalar enlistments are registered in the
> +  user's Git config. This usually does not represent any problem because it is
> +  rare for a user to register an enlistment. However, in Scalar's functional
> +  tests, Scalar enlistments are created galore, and in parallel, which can lead
> +  to lock contention. This patch series works around that problem by re-trying
> +  to lock the config file in a gentle fashion.
> +
> +- `scalar-extra-docs`: Add some extensive documentation that has been written
> +  in the original Scalar project (all subject to discussion, of course).
> +
> +- `optionally-install-scalar`: Now that Scalar is feature (and documentation)
> +  complete and is verified in CI builds, let's offer to install it.
> +
> +- `move-scalar-to-toplevel`: Now that Scalar is complete, let's move it next to
> +  `gitk-git/` and to `git-gui/`, making it a top-level command.

This final one is where we can make the final call about where Scalar should
exist in the tree and how optional it should be. This would also move the
Scalar man pages into Documentation/, along with possibly the docs from
'scalar-extra-docs', and the tests into t/. The benefit of leaving this until
the end is that we can see the entirety of Scalar before making a final call.

> +The following two patch series exist, but there is no plan to integrate them
> +into Git's source tree:
> +
> +- `scalar-with-gvfs`: The primary purpose of this patch series is to support
> +  existing Scalar users whose repositories are hosted in Azure Repos (which
> +  does not support Git's partial clones, but supports its predecessor, the GVFS
> +  protocol, which is used by Scalar to emulate the partial clone).
> +
> +  Since the GVFS protocol will never be supported by core Git, this patch
> +  series will remain in Microsoft's fork of Git.
> +
> +- `run-scalar-functional-tests`: The Scalar project developed a quite
> +  comprehensive set of integration tests (or, "Functional Tests"). They are the
> +  sole remaining part of the original C#-based Scalar project, and this patch
> +  adds a GitHub workflow that runs them all.
> +
> +  Since the tests partially depend on features that are only provided in the
> +  `scalar-with-gvfs` patch series, this patch cannot be upstreamed.

These topics (in some form or another) exist on microsoft/git and are available
via GPL, so we don't intend to say "we are withholding these patches" but instead
are saying "We don't think the Git community is interested in these patches."
There are some interesting ideas there, but the implementation is too specific to
Azure Repos to be of much help in general. These still exist mainly because the
GVFS protocol is what Azure Repos has instead of partial clone. We are focused
instead on improving partial clone.

Thanks,
-Stolee

Copy link

@gitgitgadget gitgitgadget bot Nov 18, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Johannes Schindelin wrote (reply to this):

Hi Stolee,

On Wed, 17 Nov 2021, Derrick Stolee wrote:

> On 11/17/2021 9:19 AM, Johannes Schindelin via GitGitGadget wrote:
> > From: Johannes Schindelin <[email protected]>
> >
> > The Scalar command will be contributed incrementally, over a bunch of
> > patch series. Let's document what Scalar is about, and then describe the
> > patch series that are planned.
> >
> > Signed-off-by: Johannes Schindelin <[email protected]>
> > ---
> >  contrib/scalar/README.md | 71 ++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 71 insertions(+)
> >  create mode 100644 contrib/scalar/README.md
> >
> > diff --git a/contrib/scalar/README.md b/contrib/scalar/README.md
> > new file mode 100644
> > index 00000000000..7898a683ba5
> > --- /dev/null
> > +++ b/contrib/scalar/README.md
> > @@ -0,0 +1,71 @@
> > +# Scalar - an opinionated repository management tool
> > +
> > +Scalar is an add-on to Git, helping Git scale to very large repositories and
> > +worktrees.
>
> I would rephrase this as "Scalar is an add-on to Git that helps users take
> advantage of advanced performance features in Git."

Good idea!

> Git scales just fine, only it helps to enable some features that are off
> by default.
>
> > Originally implemented in C# using .NET Core, based on the learnings
> > +from the VFS for Git project, most of the techniques developed by the Scalar
> > +project have been integrated into core Git already:
> > +
> > +* partial clone,
> > +* commit graphs,
> > +* multi-pack index,
> > +* sparse checkout (cone mode),
> > +* scheduled background maintenance,
> > +* etc
> > +
> > +This directory contains the remaining parts of Scalar that are not (yet) in
> > +core Git.
> > +
> > +## Roadmap
> > +
> > +The idea is to populate this directory via incremental patch series and
> > +eventually move to a top-level directory next to `gitk-git/` and to `git-gui/`. The
> > +current plan involves the following patch series:
> > +
> > +- `scalar-the-beginning`: The initial patch series which sets up
> > +  `contrib/scalar/` and populates it with a minimal `scalar` command that
> > +  demonstrates the fundamental ideas.
> > +
> > +- `scalar-c-and-C`: The `scalar` command learns about two options that can be
> > +  specified before the command, `-c <key>=<value>` and `-C <directory>`.
> > +
> > +- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.
> > +
> > +- `scalar-and-builtin-fsmonitor`: The built-in FSMonitor is enabled in `scalar
> > +  init` and in `scalar clone`, for an enormous performance boost when working
> > +  in large worktrees. This patch series necessarily depends on Jeff Hostetler's
> > +  FSMonitor patch series to be integrated into Git.
>
> You say 'scalar init' but do you mean 'scalar register'?

D'oh. Yes, I meant `scalar register`. I was thinking of `git init` too
much when I wrote that.

> > +- `scalar-gentler-config-locking`: Scalar enlistments are registered in the
> > +  user's Git config. This usually does not represent any problem because it is
> > +  rare for a user to register an enlistment. However, in Scalar's functional
> > +  tests, Scalar enlistments are created galore, and in parallel, which can lead
> > +  to lock contention. This patch series works around that problem by re-trying
> > +  to lock the config file in a gentle fashion.
> > +
> > +- `scalar-extra-docs`: Add some extensive documentation that has been written
> > +  in the original Scalar project (all subject to discussion, of course).
> > +
> > +- `optionally-install-scalar`: Now that Scalar is feature (and documentation)
> > +  complete and is verified in CI builds, let's offer to install it.
> > +
> > +- `move-scalar-to-toplevel`: Now that Scalar is complete, let's move it next to
> > +  `gitk-git/` and to `git-gui/`, making it a top-level command.
>
> This final one is where we can make the final call about where Scalar should
> exist in the tree and how optional it should be. This would also move the
> Scalar man pages into Documentation/, along with possibly the docs from
> 'scalar-extra-docs', and the tests into t/. The benefit of leaving this until
> the end is that we can see the entirety of Scalar before making a final call.

Yes.

It allows the current patch series to focus on the core functionality of
Scalar. The `move-scalar-to-toplevel` patch series will present an
excellent opportunity to discuss the merits and complications of accepting
Scalar as a top-level command into Git, without having to delay the
current patch series any further.

> > +The following two patch series exist, but there is no plan to integrate them
> > +into Git's source tree:
> > +
> > +- `scalar-with-gvfs`: The primary purpose of this patch series is to support
> > +  existing Scalar users whose repositories are hosted in Azure Repos (which
> > +  does not support Git's partial clones, but supports its predecessor, the GVFS
> > +  protocol, which is used by Scalar to emulate the partial clone).
> > +
> > +  Since the GVFS protocol will never be supported by core Git, this patch
> > +  series will remain in Microsoft's fork of Git.
> > +
> > +- `run-scalar-functional-tests`: The Scalar project developed a quite
> > +  comprehensive set of integration tests (or, "Functional Tests"). They are the
> > +  sole remaining part of the original C#-based Scalar project, and this patch
> > +  adds a GitHub workflow that runs them all.
> > +
> > +  Since the tests partially depend on features that are only provided in the
> > +  `scalar-with-gvfs` patch series, this patch cannot be upstreamed.
>
> These topics (in some form or another) exist on microsoft/git and are available
> via GPL, so we don't intend to say "we are withholding these patches" but instead
> are saying "We don't think the Git community is interested in these patches."
> There are some interesting ideas there, but the implementation is too specific to
> Azure Repos to be of much help in general. These still exist mainly because the
> GVFS protocol is what Azure Repos has instead of partial clone. We are focused
> instead on improving partial clone.

Good point. What I wrote does not fully reflect that. I have changed it.

Do you see anything in the remainder of the patch series that still needs
to be improved?

Thanks,
Dscho


Scalar is an add-on to Git that helps users take advantage of advanced
performance features in Git. Originally implemented in C# using .NET Core,
based on the learnings from the VFS for Git project, most of the techniques
developed by the Scalar project have been integrated into core Git already:

* partial clone,
* commit graphs,
* multi-pack index,
* sparse checkout (cone mode),
* scheduled background maintenance,
* etc

This directory contains the remaining parts of Scalar that are not (yet) in
core Git.

## Roadmap

The idea is to populate this directory via incremental patch series and
eventually move to a top-level directory next to `gitk-git/` and to `git-gui/`. The
current plan involves the following patch series:

- `scalar-the-beginning`: The initial patch series which sets up
`contrib/scalar/` and populates it with a minimal `scalar` command that
demonstrates the fundamental ideas.

- `scalar-c-and-C`: The `scalar` command learns about two options that can be
specified before the command, `-c <key>=<value>` and `-C <directory>`.

- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.

- `scalar-and-builtin-fsmonitor`: The built-in FSMonitor is enabled in `scalar
register` and in `scalar clone`, for an enormous performance boost when
working in large worktrees. This patch series necessarily depends on Jeff
Hostetler's FSMonitor patch series to be integrated into Git.

- `scalar-gentler-config-locking`: Scalar enlistments are registered in the
user's Git config. This usually does not represent any problem because it is
rare for a user to register an enlistment. However, in Scalar's functional
tests, Scalar enlistments are created galore, and in parallel, which can lead
to lock contention. This patch series works around that problem by re-trying
to lock the config file in a gentle fashion.

- `scalar-extra-docs`: Add some extensive documentation that has been written
in the original Scalar project (all subject to discussion, of course).

- `optionally-install-scalar`: Now that Scalar is feature (and documentation)
complete and is verified in CI builds, let's offer to install it.

- `move-scalar-to-toplevel`: Now that Scalar is complete, let's move it next to
`gitk-git/` and to `git-gui/`, making it a top-level command.

The following two patch series exist in Microsoft's fork of Git and are
publicly available. There is no current plan to upstream them, not because I
want to withhold these patches, but because I don't think the Git community is
interested in these patches.

There are some interesting ideas there, but the implementation is too specific
to Azure Repos and/or VFS for Git to be of much help in general (and also: my
colleagues tried to upstream some patches already and the enthusiasm for
integrating things related to Azure Repos and VFS for Git can be summarized in
very, very few words).

These still exist mainly because the GVFS protocol is what Azure Repos has
instead of partial clone, while Git is focused on improving partial clone:

- `scalar-with-gvfs`: The primary purpose of this patch series is to support
existing Scalar users whose repositories are hosted in Azure Repos (which
does not support Git's partial clones, but supports its predecessor, the GVFS
protocol, which is used by Scalar to emulate the partial clone).

Since the GVFS protocol will never be supported by core Git, this patch
series will remain in Microsoft's fork of Git.

- `run-scalar-functional-tests`: The Scalar project developed a quite
comprehensive set of integration tests (or, "Functional Tests"). They are the
sole remaining part of the original C#-based Scalar project, and this patch
adds a GitHub workflow that runs them all.

Since the tests partially depend on features that are only provided in the
`scalar-with-gvfs` patch series, this patch cannot be upstreamed.
Loading