diff --git a/contrib/scalar/docs/getting-started.md b/contrib/scalar/docs/getting-started.md index ef7ea07b0f..d512533032 100644 --- a/contrib/scalar/docs/getting-started.md +++ b/contrib/scalar/docs/getting-started.md @@ -18,8 +18,9 @@ Creating a new Scalar clone --------------------------------------------------- The `clone` verb creates a local enlistment of a remote repository using the -partial clone feature available e.g. on GitHub. - +partial clone feature available e.g. on GitHub, or using the +[GVFS protocol](https://github.com/microsoft/VFSForGit/blob/HEAD/Protocol.md), +such as Azure Repos. ``` scalar clone [options] [] @@ -68,11 +69,26 @@ in ``. These options allow a user to customize their initial enlistment. * `--full-clone`: If specified, do not initialize the sparse-checkout feature. - All files will be present in your `src` directory. This uses a Git partial - clone: blobs are downloaded on demand. + All files will be present in your `src` directory. This behaves very similar + to a Git partial clone in that blobs are downloaded on demand. However, it + will use the GVFS protocol to download all Git objects. + +* `--cache-server-url=`: If specified, set the intended cache server to + the specified ``. All object queries will use the GVFS protocol to this + `` instead of the origin remote. If the remote supplies a list of + cache servers via the `/gvfs/config` endpoint, then the `clone` command + will select a nearby cache server from that list. * `--branch=`: Specify the branch to checkout after clone. +* `--local-cache-path=`: Use this option to override the path for the + local Scalar cache. If not specified, then Scalar will select a default + path to share objects with your other enlistments. On Windows, this path + is a subdirectory of `:\.scalarCache\`. On Mac, this path is a + subdirectory of `~/.scalarCache/`. The default cache path is recommended so + multiple enlistments of the same remote repository share objects on the + same device. + ### Advanced Options The options below are not intended for use by a typical user. These are diff --git a/contrib/scalar/docs/index.md b/contrib/scalar/docs/index.md index f9f5ab06e0..4f56e2b0eb 100644 --- a/contrib/scalar/docs/index.md +++ b/contrib/scalar/docs/index.md @@ -28,10 +28,14 @@ these features for that repo (except partial clone) and start running suggested maintenance in the background using [the `git maintenance` feature](https://git-scm.com/docs/git-maintenance). -Repos cloned with the `scalar clone` command use partial clone to significantly -reduce the amount of data required to get started using a repository. By -delaying all blob downloads until they are required, Scalar allows you to work -with very large repositories quickly. +Repos cloned with the `scalar clone` command use partial clone or the +[GVFS protocol](https://github.com/microsoft/VFSForGit/blob/HEAD/Protocol.md) +to significantly reduce the amount of data required to get started +using a repository. By delaying all blob downloads until they are required, +Scalar allows you to work with very large repositories quickly. The GVFS +protocol allows a network of _cache servers_ to serve objects with lower +latency and higher throughput. The cache servers also reduce load on the +central server. Documentation ------------- @@ -42,7 +46,7 @@ Documentation * [Troubleshooting](troubleshooting.md): Collect diagnostic information or update custom settings. Includes - `scalar diagnose`. + `scalar diagnose` and `scalar cache-server`. * [The Philosophy of Scalar](philosophy.md): Why does Scalar work the way it does, and how do we make decisions about its future? diff --git a/contrib/scalar/docs/philosophy.md b/contrib/scalar/docs/philosophy.md index 51486a75e4..e3dfa025a2 100644 --- a/contrib/scalar/docs/philosophy.md +++ b/contrib/scalar/docs/philosophy.md @@ -13,22 +13,27 @@ Scalar only to configure those new settings. In particular, we ported features like background maintenance to Git to make Scalar simpler and make Git more powerful. -Services such as GitHub support partial clone , a standard adopted by the Git -project to download only part of the Git objects when cloning, and fetching -further objects on demand. If your hosting service supports partial clone, then -we absolutely recommend it as a way to greatly speed up your clone and fetch -times and to reduce how much disk space your Git repository requires. Scalar -will help with this! +Scalar ships inside [a custom version of Git][microsoft-git], but we are +working to make it available in other forks of Git. The only feature +that is not intended to ever reach the standard Git client is Scalar's use +of [the GVFS Protocol][gvfs-protocol], which is essentially an older +version of [Git's partial clone feature](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) +that was available first in Azure Repos. Services such as GitHub support +only partial clone instead of the GVFS protocol because that is the +standard adopted by the Git project. If your hosting service supports +partial clone, then we absolutely recommend it as a way to greatly speed +up your clone and fetch times and to reduce how much disk space your Git +repository requires. Scalar will help with this! -Most of the value of Scalar can be found in the core Git client. However, most -of the advanced features that really optimize Git's performance are off by -default for compatibility reasons. To really take advantage of Git's latest and -greatest features, you either need to study the [`git config` -documentation](https://git-scm.com/docs/git-config) and regularly read [the Git -release notes](https://github.com/git/git/tree/master/Documentation/RelNotes). +If you don't use the GVFS Protocol, then most of the value of Scalar can +be found in the core Git client. However, most of the advanced features +that really optimize Git's performance are off by default for compatibility +reasons. To really take advantage of Git's latest and greatest features, +you either need to study the [`git config` documentation](https://git-scm.com/docs/git-config) +and regularly read [the Git release notes](https://github.com/git/git/tree/master/Documentation/RelNotes). Even if you do all that work and customize your Git settings on your machines, -you likely will want to share those settings with other team members. Or, you -can just use Scalar! +you likely will want to share those settings with other team members. +Or, you can just use Scalar! Using `scalar register` on an existing Git repository will give you these benefits: diff --git a/contrib/scalar/docs/troubleshooting.md b/contrib/scalar/docs/troubleshooting.md index 8ec56ad437..c54d2438f2 100644 --- a/contrib/scalar/docs/troubleshooting.md +++ b/contrib/scalar/docs/troubleshooting.md @@ -18,3 +18,23 @@ files for that repository. This includes: As the `diagnose` command completes, it provides the path of the resulting zip file. This zip can be attached to bug reports to make the analysis easier. + +Modifying Configuration Values +------------------------------ + +The Scalar-specific configuration is only available for repos using the +GVFS protocol. + +### Cache Server URL + +When using an enlistment cloned with `scalar clone` and the GVFS protocol, +you will have a value called the cache server URL. Cache servers are a feature +of the GVFS protocol to provide low-latency access to the on-demand object +requests. This modifies the `gvfs.cache-server` setting in your local Git config +file. + +Run `scalar cache-server --get` to see the current cache server. + +Run `scalar cache-server --list` to see the available cache server URLs. + +Run `scalar cache-server --set=` to set your cache server to ``.