chrisd8088/scalar

Scalar: A set of tools and extensions for Git to allow very large monorepos to run on Git without a virtualization layer

What is Scalar?

Scalar is an opinionated repository management tool. By creating new repositories or registering existing repositories with Scalar, your Git experience will speed up. Scalar sets advanced Git config settings, maintains your repositories in the background, and helps reduce data sent across the network.

You can learn more about Scalar in this video: Git at Scale for Everyone.

Table of Contents

• Getting Started
• Example Workflow
• License
• Code of Conduct

Getting Started

Full details can be found in our documentation page.

Installing on macOS

Scalar is installed and updated on macOS via Homebrew.

brew tap microsoft/git
brew cask install scalar

If you wish to use the GVFS Protocol, then you will instead need the cask that uses our custom fork of Git:

brew tap microsoft/git
brew cask install scalar-azrepos

When new versions of Scalar are available, you can upgrade in a few different ways. First, you can use brew:

brew update

# Use only one of the following, depending on which you have installed:
brew upgrade --cask scalar
brew upgrade --cask scalar-azrepos

Alternatively, you can run scalar upgrade and it will run the necessary brew commands on your behalf.

If your repository has many files in the working directory, then you might want to install Watchman, which Scalar will detect and configure with Git's File System Monitor feature.

brew install watchman

Installing on Windows

To install Scalar on Windows, download Installers_Windows_Release.zip from the latest release and extract all of the files. Run the contained installers for Git and Scalar, with names matching these patterns:

• Git\Git-2.XX.Y-vfs.*.*-64-bit.exe
• Scalar\SetupScalar.YY.MM.<sprint>.<minor>.exe

Note: we are investigating package management tools to have the Windows install process be as simple as the brew process on macOS. See #433 for progress on this feature.

Basic Scalar Use

To create a new local repository from a remote repository, run

scalar clone [--full-clone] <url> [<dir>]

If the given <url> is hosted by Azure Repos, then the clone will use the GVFS Protocol to reduce the amount of data sent across the network. Otherwise, this will attempt to use Git's partial clone feature to achieve similar results.

If you already have a local Git repository and do not want to clone a new one, you can get many of the benefits of Scalar by registering your repository using the scalar register command.

scalar register

After either of these commands, your repositories will be initialized with advanced Git performance features and will be maintained in the background according to our recommended maintenance schedule.

Example Workflow

If you want to get a feel for an initial workflow with a test project, here are some commands that clone our test repo and initialize the sparse-checkout definition to grow the working directory.

Run these commands in Terminal on macOS or in Git Bash on Windows.

First, clone the repository using the GVFS protocol.

$ scalar clone https://dev.azure.com/gvfs/ci/_git/ForTests
Clone parameters:
  Repo URL:     https://dev.azure.com/gvfs/ci/_git/ForTests
  Branch:       Default
  Cache Server: Default
  Local Cache:  C:\.scalarCache
  Destination:  C:\_git\ForTests
  FullClone:     False
Authenticating...
Querying remote for config...
Using cache server: None (https://dev.azure.com/gvfs/ci/_git/ForTests)
Cloning...
Fetching commits and trees from origin (no cache server)...
Configuring Watchman...
Validating repo...
Complete!

Then, navigate into the repository's src directory. (Related: Why does scalar clone create a src folder?)

$ cd ForTests/src
$ ls -a
./   .git/           .gitignore         GvFlt_EULA.md  License.md    Protocol.md  Settings.StyleCop
../  .gitattributes  AuthoringTests.md  GVFS.sln       nuget.config  Readme.md

This directory is the working directory, which contains all files tracked by Git. It also includes the .git directory and its contents.

The working directory does not contain any subdirectories (other than the .git directory). This is due to the initial sparse-checkout definition which only cares about the files at root. We can expand the sparse-checkout using the git sparse-checkout set and git sparse-checkout add commands:

$ git sparse-checkout set GVFS/GVFS.Common GVFS/GVFS.UnitTests GitHooksLoader
$ ls -a
./   .git/           .gitignore         GitHooksLoader/  GVFS/     License.md    Protocol.md  Settings.StyleCop
../  .gitattributes  AuthoringTests.md  GvFlt_EULA.md    GVFS.sln  nuget.config  Readme.md

$ ls GVFS
GVFS.Common/  GVFS.UnitTests/  LibGit2Sharp.NativeBinaries.props  ProjectedFSLib.NativeBinaries.props

$ git sparse-checkout add GVFS/GVFS
$ ls GVFS
GVFS/  GVFS.Common/  GVFS.UnitTests/  LibGit2Sharp.NativeBinaries.props  ProjectedFSLib.NativeBinaries.props

Learn more about sparse-checkout here.

License

The Scalar source code in this repo is available under the MIT license. See License.md.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.