forked from git-for-windows/git
-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This merges the upstreamable part of the Scalar patches. Minor merge conflicts (caused by the gvfs-helper) were resolved trivially. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
- Loading branch information
Showing
14 changed files
with
384 additions
and
11 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
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
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
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,98 @@ | ||
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 | ||
--------------------------------------------------- | ||
|
||
The `clone` verb creates a local enlistment of a remote repository using the | ||
partial clone feature available e.g. on GitHub. | ||
|
||
|
||
``` | ||
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 uses a Git partial | ||
clone: blobs are downloaded on demand. | ||
|
||
* `--branch=<ref>`: Specify the branch to checkout after clone. | ||
|
||
### 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,50 @@ | ||
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 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. | ||
|
||
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`. | ||
|
||
* [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.