forked from git-for-windows/git
-
Notifications
You must be signed in to change notification settings - Fork 97
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #377: Update README to include Scalar CLI details
I created these as `fixup!` commits so they get squashed in the next major release rebase, but also so they can be reviewed commit-by-commit. * The first is a doozy, adjusting line widths and otherwise updating some minor things here and there. * The rest are small and explained by the body of the commit messages. * One non-`fixup!` commit adds the `docs/` directory from `microsoft/scalar`, with some edits due to the C port of Scalar.
- Loading branch information
Showing
6 changed files
with
421 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| Frequently Asked Questions | ||
| ========================== | ||
|
|
||
| Using Scalar | ||
| ------------ | ||
|
|
||
| ### I don't want a sparse clone, I want every file after I clone! | ||
|
|
||
| Run `scalar clone --full-clone <url>` to initialize your repo to include | ||
| every file. You can switch to a sparse-checkout later by running | ||
| `git sparse-checkout init --cone`. | ||
|
|
||
| ### I already cloned without `--full-clone`. How do I get everything? | ||
|
|
||
| Run `git sparse-checkout disable`. | ||
|
|
||
| Scalar Design Decisions | ||
| ----------------------- | ||
|
|
||
| There may be many design decisions within Scalar that are confusing at first | ||
| glance. Some of them may cause friction when you use Scalar with your existing | ||
| repos and existing habits. | ||
|
|
||
| > Scalar has the most benefit when users design repositories | ||
| > with efficient patterns. | ||
| For example: Scalar uses the sparse-checkout feature to limit the size of the | ||
| working directory within a large monorepo. It is designed to work efficiently | ||
| with monorepos that are highly componentized, allowing most developers to | ||
| need many fewer files in their daily work. | ||
|
|
||
| ### Why does `scalar clone` create a `<repo>/src` folder? | ||
|
|
||
| Scalar uses a file system watcher to keep track of changes under this `src` folder. | ||
| Any activity in this folder is assumed to be important to Git operations. By | ||
| creating the `src` folder, we are making it easy for your build system to | ||
| create output folders outside the `src` directory. We commonly see systems | ||
| create folders for build outputs and package downloads. Scalar itself creates | ||
| these folders during its builds. | ||
|
|
||
| Your build system may create build artifacts such as `.obj` or `.lib` files | ||
| next to your source code. These are commonly "hidden" from Git using | ||
| `.gitignore` files. Having such artifacts in your source tree creates | ||
| additional work for Git because it needs to look at these files and match them | ||
| against the `.gitignore` patterns. | ||
|
|
||
| By following the `src` pattern Scalar tries to establish and placing your build | ||
| intermediates and outputs parallel with the `src` folder and not inside it, | ||
| you can help optimize Git command performance for developers in the repository | ||
| by limiting the number of files Git needs to consider for many common | ||
| operations. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| Getting Started | ||
| =============== | ||
|
|
||
| Registering existing Git repos | ||
| ------------------------------ | ||
|
|
||
| To add a repository to the list of registered repos, run `scalar register [<path>]`. | ||
| If `<path>` is not provided, then the "current repository" is discovered from | ||
| the working directory by scanning the parent paths for a path containing a `.git` | ||
| folder, possibly inside a `src` folder. | ||
|
|
||
| To see which repositories are currently tracked by the service, run | ||
| `scalar list`. | ||
|
|
||
| Run `scalar unregister [<path>]` to remove the repo from this list. | ||
|
|
||
| Creating a new Scalar clone using the GVFS Protocol | ||
| --------------------------------------------------- | ||
|
|
||
| The `clone` verb creates a local enlistment of a remote repository using the | ||
| [GVFS protocol](https://github.com/microsoft/VFSForGit/blob/HEAD/Protocol.md), | ||
| such as Azure Repos. | ||
|
|
||
| ``` | ||
| scalar clone [options] <url> [<dir>] | ||
| ``` | ||
|
|
||
| Create a local copy of the repository at `<url>`. If specified, create the `<dir>` | ||
| directory and place the repository there. Otherwise, the last section of the `<url>` | ||
| will be used for `<dir>`. | ||
|
|
||
| At the end, the repo is located at `<dir>/src`. By default, the sparse-checkout | ||
| feature is enabled and the only files present are those in the root of your | ||
| Git repository. Use `git sparse-checkout set` to expand the set of directories | ||
| you want to see, or `git sparse-checkout disable` to expand to all files. You | ||
| can explore the subdirectories outside your sparse-checkout specification using | ||
| `git ls-tree HEAD`. | ||
|
|
||
| ### Sparse Repo Mode | ||
|
|
||
| By default, Scalar reduces your working directory to only the files at the | ||
| root of the repository. You need to add the folders you care about to build up | ||
| to your working set. | ||
|
|
||
| * `scalar clone <url>` | ||
| * Please choose the **Clone with HTTPS** option in the `Clone Repository` dialog in Azure Repos, not **Clone with SSH**. | ||
| * `cd <root>\src` | ||
| * At this point, your `src` directory only contains files that appear in your root | ||
| tree. No folders are populated. | ||
| * Set the directory list for your sparse-checkout using: | ||
| 1. `git sparse-checkout set <dir1> <dir2> ...` | ||
| 2. `git sparse-checkout set --stdin < dir-list.txt` | ||
| * Run git commands as you normally would. | ||
| * To fully populate your working directory, run `git sparse-checkout disable`. | ||
|
|
||
| If instead you want to start with all files on-disk, you can clone with the | ||
| `--full-clone` option. To enable sparse-checkout after the fact, run | ||
| `git sparse-checkout init --cone`. This will initialize your sparse-checkout | ||
| patterns to only match the files at root. | ||
|
|
||
| If you are unfamiliar with what directories are available in the repository, | ||
| then you can run `git ls-tree -d --name-only HEAD` to discover the directories | ||
| at root, or `git ls-tree -d --name-only HEAD <path>` to discover the directories | ||
| in `<path>`. | ||
|
|
||
| ### Options | ||
|
|
||
| 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 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=<url>`: If specified, set the intended cache server to | ||
| the specified `<url>`. All object queries will use the GVFS protocol to this | ||
| `<url>` instead of the origin remote. If the remote supplies a list of | ||
| cache servers via the `<url>/gvfs/config` endpoint, then the `clone` command | ||
| will select a nearby cache server from that list. | ||
|
|
||
| * `--branch=<ref>`: Specify the branch to checkout after clone. | ||
|
|
||
| * `--local-cache-path=<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 `<Volume>:\.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 | ||
| usually used by build machines to create a temporary enlistment that | ||
| operates on a single commit. | ||
|
|
||
| * `--single-branch`: Use this option to only download metadata for the branch | ||
| that will be checked out. This is helpful for build machines that target | ||
| a remote with many branches. Any `git fetch` commands after the clone will | ||
| still ask for all branches. | ||
|
|
||
| * `--no-prefetch`: Use this option to not prefetch commits after clone. This | ||
| is not recommended for anyone planning to use their clone for history | ||
| traversal. Use of this option will make commands like `git log` or | ||
| `git pull` extremely slow and is therefore not recommended. | ||
|
|
||
| Removing a Scalar Clone | ||
| ----------------------- | ||
|
|
||
| Since the `scalar clone` command sets up a file-system watcher (when available), | ||
| that watcher could prevent deleting the enlistment. Run `scalar delete <path>` | ||
| from outside of your enlistment to unregister the enlistment from the filesystem | ||
| watcher and delete the enlistment at `<path>`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| Scalar: Enabling Git at Scale | ||
| ============================= | ||
|
|
||
| Scalar is a tool that helps Git scale to some of the largest Git repositories. | ||
| It achieves this by enabling some advanced Git features, such as: | ||
|
|
||
| * *Partial clone:* reduces time to get a working repository by not | ||
| downloading all Git objects right away. | ||
|
|
||
| * *Background prefetch:* downloads Git object data from all remotes every | ||
| hour, reducing the amount of time for foreground `git fetch` calls. | ||
|
|
||
| * *Sparse-checkout:* limits the size of your working directory. | ||
|
|
||
| * *File system monitor:* tracks the recently modified files and eliminates | ||
| the need for Git to scan the entire worktree. | ||
|
|
||
| * *Commit-graph:* accelerates commit walks and reachability calculations, | ||
| speeding up commands like `git log`. | ||
|
|
||
| * *Multi-pack-index:* enables fast object lookups across many pack-files. | ||
|
|
||
| * *Incremental repack:* Repacks the packed Git data into fewer pack-file | ||
| without disrupting concurrent commands by using the multi-pack-index. | ||
|
|
||
| By running `scalar register` in any Git repo, Scalar will automatically enable | ||
| 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 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 | ||
| ------------- | ||
|
|
||
| * [Getting Started](getting-started.md): Get started with Scalar. | ||
| Includes `scalar register`, `scalar unregister`, `scalar clone`, and | ||
| `scalar delete`. | ||
|
|
||
| * [Troubleshooting](troubleshooting.md): | ||
| Collect diagnostic information or update custom settings. Includes | ||
| `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? | ||
|
|
||
| * [Frequently Asked Questions](faq.md) |
Oops, something went wrong.