Merge pull request #181: Create the "docs/" folder with some user-facing documentation

Create a set of docs that we can expand more as we prepare for public release.

I created the markdown docs inside the `docs/` folder as that can be used as the root of a GitHub pages deployment. The intention is that `index.md` will be rendered as the homepage, and will link to the other documents.

I included docs for the verbs we will definitely keep into the future. If we change how these verbs work, then we will want to update the docs. If we do not remove all of the other verbs in time for public release, then we should add docs for them.

The "frequently asked questions" is a bit pre-emptive. No one actually asked these questions, but I anticipate them being asked.

As an aside, I added a "repository image" to the repo, so I added the SVG and PNG for that, too.

Author: derrickstolee

Scalar/Images/scalar-card.png

@@ -0,0 +1,67 @@
+`scalar clone`
+==============
+
+The `clone` verb creates a local enlistment of a remote repository.
+
+Usage
+-----
+
+`scalar clone [options] <url> [<dir>]`
+
+Description
+-----------
+
+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`.
+
+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.
+

Scalar/Images/scalar-card.svg

@@ -0,0 +1,29 @@
+`scalar diagnose`
+=================
+
+The `diagnose` verb collects logs and config details for the current repository.
+The resulting zip file helps root-cause issues.
+
+Usage
+-----
+
+`scalar diagnose`
+
+Description
+-----------
+
+When run inside your repository, creates a zip file containing several important
+files for that repository. This includes:
+
+* All log files from `scalar` commands run in the enlistment since `clone`.
+
+* Log files from the Scalar service.
+
+* Configuration files from your `.git` folder, such as the `config` file,
+  `index`, `hooks`, and `refs`.
+
+* A summary of your shared object cache, including the number of loose objects
+  and the names and sizes of pack-files.
+
+As the `diagnose` command completes, it provides the path of the resulting
+zip file. This zip can be sent to the support team for investigation.

docs/commands/scalar-clone.md

@@ -0,0 +1,40 @@
+`scalar maintenance`
+====================
+
+The `maintenance` verb runs one of several maintenance tasks that normally
+happen in the background.
+
+Usage
+-----
+
+`scalar maintenance --task=<task> [--batch-size=<size>]`
+
+Description
+-----------
+
+Run the maintenance task specified by `<task>`. The options are:
+
+* `commit-graph`: Update the Git commit-graph to include all reachable
+  commits. After writing a new file, verify the file was computed successfully.
+  This helps commands like `git log --graph` work very quickly.
+
+* `commits-and-trees`: Download the latest set of commit and tree packs from
+   the cache server or the origin remote.
+
+* `loose-objects`: Examine the loose objects contained in the shared object
+  cache. First, delete any loose objects that are currently located in
+  pack-files. Second, create a new pack-file containing the remaining loose
+  objects. The pack will contain up to 50,000 objects, leaving any extra
+  objects for the next run of the `loose-objects` step. This happens in the
+  background once a day.
+
+* `pack-files`:  Update the Git multi-pack-index and repack small pack-files
+  into larger pack-files.  Scalar downloads many pack-files during the
+  `commits-and-trees` step, or during `git checkout` commands. The `pack-files`
+  step updates the  Git multi-pack-index to improve lookup speed. Further, it
+  combines pack-files into larger files to reduce the total pack-file count.
+  This step is designed to work without blocking concurrent processes by only
+  deleting pack-files after they were marked as "unused" for at least a day.
+  This step allows using the `--batch-size=<size>` option. By default, the
+  batch-size is "2g" for two gigabytes. This batch size signifies the goal
+  size of a repacked pack-file.

docs/commands/scalar-diagnose.md

@@ -0,0 +1,29 @@
+`scalar upgrade`
+================
+
+The `upgrade` verb checks for the latest version of Scalar, and can allow
+upgrading to that version.
+
+Usage
+-----
+
+`scalar upgrade <options>`
+
+Description
+-----------
+
+Check for a new Scalar version. With `--confirm`, will perform the upgrade
+by downloading the new version and running the installer.
+
+
+Options
+-------
+
+* `--confirm`: Pass in this flag to actually install the newest release.
+
+* `--dry-run`: Display progress and errors, but don't install Scalar. Not
+  compatible with the `--confirm` option.
+
+* `--no-verify`: This parameter is currently required for upgrade on
+   macOS.
+

docs/commands/scalar-maintenance.md

@@ -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 componetized, 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 into 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 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.

docs/commands/scalar-upgrade.md

@@ -0,0 +1,47 @@
+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:
+
+* *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.
+
+Scalar clones also use the
+[GVFS protocol](https://github.com/microsoft//VFSForGit/blob/master/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. This 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
+-------------
+
+* [Frequently Asked Questions](faq.md)
+
+Scalar Commands
+---------------
+
+* [`scalar clone`](commands/scalar-clone.md): Create a local enlistment of
+  a remote repository.
+
+* [`scalar upgrade`](commands/scalar-upgrade.md): Upgrade your version of
+  Scalar to the latest available release.
+
+* [`scalar diagnose`](commands/scalar-diagnose.md): Collect diagnostic data
+  to assist troubleshooting.
+
+* [`scalar maintenance`](commands/scalar-maintenance.md): Manually process
+  Git data for efficiency. Normally run in the background by Scalar Service.
+