docs: add basic user-facing documentation

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>

Readme.md

@@ -7,10 +7,15 @@
 
 ## What is VFS for Git?
 
-VFS stands for Virtual File System. VFS for Git virtualizes the file system beneath your git repo so that git and all tools
-see what appears to be a normal repo, but VFS for Git only downloads objects as they are needed. VFS for Git also manages the files that git will consider,
-to ensure that git operations like status, checkout, etc., can be as quick as possible because they will only consider the files
-that the user has accessed, not all files in the repo.
+VFS stands for Virtual File System. VFS for Git virtualizes the file system
+beneath your Git repository so that Git and all tools see what appears to be a
+regular working directory, but VFS for Git only downloads objects as they
+are needed. VFS for Git also manages the files that Git will consider, to
+ensure that Git operations such as `status`, `checkout`, etc., can be as quick
+as possible because they will only consider the files that the user has
+accessed, not all files in the repository.
+
+[See our documentation](docs/index.md) for instructions to get started.
 
 ## New name
 
@@ -22,7 +27,7 @@ built executables, and releases may still refer to the old GVFS name. See https:
 * VFS for Git requires Windows 10 Anniversary Update (Windows 10 version 1607) or later
 * Run the latest GVFS and Git for Windows installers from https://github.com/Microsoft/VFSForGit/releases
 
-## Building VFS for Git on Windows
+## Building VFS for Git
 
 If you'd like to build your own VFS for Git Windows installer:
 * Install Visual Studio 2017 Community Edition or higher (https://www.visualstudio.com/downloads/).
@@ -53,19 +58,23 @@ The installer can now be found at `C:\Repos\VFSForGit\BuildOutput\GVFS.Installer
 
 ## Trying out VFS for Git
 
-* VFS for Git will work with any git service that supports the GVFS [protocol](Protocol.md). For example, you can create a repo in
-Azure DevOps (https://azure.microsoft.com/services/devops/), and push some contents to it. There are two constraints:
+* VFS for Git will work with any Git service that supports the
+  [GVFS protocol](Protocol.md). For example, you can create a repo in
+  [Azure DevOps](https://azure.microsoft.com/services/devops/), and push
+  some contents to it. There are two constraints:
   * Your repo must not enable any clean/smudge filters
   * Your repo must have a `.gitattributes` file in the root that includes the line `* -text`
 * `gvfs clone <URL of repo you just created>`
   * Please choose the **Clone with HTTPS** option in the `Clone Repository` dialog in Azure Repos, not **Clone with SSH**.
 * `cd <root>\src`
-* Run git commands as you normally would
+* Run Git commands as you normally would
 * `gvfs unmount` when done
 
 
 # Licenses
 
-The VFS for Git source code in this repo is available under the MIT license. See [License.md](License.md).
+The VFS for Git source code in this repo is available under the MIT license.
+See [License.md](License.md).
 
-VFS for Git relies on the PrjFlt filter driver, formerly known as the GvFlt filter driver, available as a prerelease NuGet package.
+VFS for Git relies on the PrjFlt filter driver, formerly known as the GvFlt
+filter driver, available as a prerelease NuGet package.

docs/faq.md

@@ -0,0 +1,34 @@
+Frequently Asked Questions
+==========================
+
+Here are some questions that users often have with VFS for Git, but are
+unrelated to [troubleshooting issues](troubleshooting.md).
+
+### Why does `gvfs clone` create a `<repo>/src` folder?
+
+VFS for Git integrates with ProjFS 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. VFS for Git 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 pattern VFS for Git 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.
+
+### Why the name change?
+
+This project was formerly known as GVFS (Git Virtual File System). It is
+undergoing a rename to VFS for Git. While the rename is in progress, the
+code, protocol, built executables, and releases may still refer to the old
+GVFS name. See https://github.com/Microsoft/VFSForGit/projects/4 for the
+latest status of the rename effort.

docs/getting-started.md

@@ -0,0 +1,96 @@
+Getting Started
+===============
+
+Repository Requirements
+-----------------------
+
+VFS for Git will work with any Git service that supports the
+[GVFS protocol](/Protocol.md). For example, you can create a repo in
+[Azure DevOps](https://azure.microsoft.com/services/devops/), and push
+some contents to it. There are two constraints:
+
+  * Your repo must not enable any clean/smudge filters
+  * Your repo must have a `.gitattributes` file in the root that includes
+    the line `* -text`
+
+
+Cloning 
+-------
+
+The `clone` verb creates a local enlistment of a remote repository using the
+[GVFS protocol](https://github.com/microsoft/VFSForGit/blob/master/Protocol.md).
+
+```
+gvfs 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`.
+
+### Options
+
+These options allow a user to customize their initial enlistment.
+
+* `--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 VFS for Git cache. If not specified, then a default path inside
+  `<Volume>:\.gvfsCache\` is used. The default cache path is recommended so
+  multiple clones 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.
+
+Mounting and Unmounting
+-----------------------
+
+Before running Git commands in your VFS for Git enlistment or reading
+files and folders inside the enlistment, a `GVFS.Mount` process must be
+running to manage the virtual file system projection.
+
+A mount process is started by a successful `gvfs clone`, and the
+enlistment is registered with `GVFS.Service` to auto-mount in the future.
+
+The `gvfs status` command checks to see if a mount process is currently
+running for the current enlistment.
+
+The `gvfs mount` command will start a new mount process and register the
+enlistment for auto-mount in the future.
+
+The `gvfs unmount` command will safely shut down the mount process and
+unregister the enlistment for auto-mount.
+
+
+Removing a VFS for Git Clone
+----------------------------
+
+Since a VFS for Git clone has a running `GVFS.Mount` process to track the
+Git index and watch updates from the ProjFS filesystem driver, you must
+first run `gvfs unmount` before deleting your repository. This will also
+remove the repository from the auto-mount feature of `GVFS.Service`.
+
+If you have deleted the enlistment or its `.gvfs` folder, then you will
+likely see alerts saying "Failed to auto-mount at path `X`". To remove
+this enlistment from the auto-mount feature, remove the appropriate line
+from the `C:\ProgramData\GVFS\GVFS.Service\repo-registry` file.

docs/index.md

@@ -0,0 +1,28 @@
+VFS for Git: Virtualized File System for Git
+============================================
+
+VFS stands for Virtual File System. VFS for Git virtualizes the file system
+beneath your Git repository so that Git and all tools see what appears to be a
+regular working directory, but VFS for Git only downloads objects as they
+are needed. VFS for Git also manages the files that Git will consider, to
+ensure that Git operations such as `status`, `checkout`, etc., can be as quick
+as possible because they will only consider the files that the user has
+accessed, not all files in the repository.
+
+Installing
+----------
+
+* VFS for Git requires Windows 10 Anniversary Update (Windows 10 version 1607) or later
+* Run the latest VFS for Git and Git for Windows installers from https://github.com/Microsoft/VFSForGit/releases
+
+Documentation
+-------------
+
+* [Getting Started](getting-started.md): Get started with VFS for Git.
+  Includes `gvfs clone`.
+
+* [Troubleshooting](troubleshooting.md):
+  Collect diagnostic information or update custom settings. Includes
+  `gvfs diagnose`, `gvfs config`, `gvfs upgrade`, and `gvfs cache-server`.
+
+* [Frequently Asked Questions](faq.md)

docs/troubleshooting.md

@@ -0,0 +1,81 @@
+Troubleshooting
+===============
+
+Deleting a VFS for Git repo
+---------------------------
+
+Since a VFS for Git clone has a running `GVFS.Mount` process to track the
+Git index and watch updates from the ProjFS filesystem driver, you must
+first run `gvfs unmount` before deleting your repository. This will also
+remove the repository from the auto-mount feature of `GVFS.Service`.
+
+If you have deleted the enlistment or its `.gvfs` folder, then you will
+likely see alerts saying "Failed to auto-mount at path `X`". To remove
+this enlistment from the auto-mount feature, remove the appropriate line
+from the `C:\ProgramData\GVFS\GVFS.Service\repo-registry` file.
+
+Upgrade
+-------
+
+The `GVFS.Service` process checks for new versions of VFS for Git daily and
+will prompt you for upgrade using a notification. To check manually, run
+`gvfs upgrade` to see if an upgrade is available. Run `gvfs upgrade --confirm`
+to actually perform the upgrade, if you wish.
+
+Diagnosing Issues
+-----------------
+
+The `gvfs diagnose` command collects logs and config details for the current
+repository. The resulting zip file helps root-cause issues.
+
+When run inside your repository, creates a zip file containing several important
+files for that repository. This includes:
+
+* All log files from `gvfs` commands run in the enlistment, including
+  maintenance steps.
+
+* Log files from the `GVFS.Service`.
+
+* Configuration files from your `.git` folder, such as the `config` file,
+  `index`, `hooks`, and `refs`.
+
+* A summary of your Git object database, 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.
+
+Modifying Configuration Values
+------------------------------
+
+### 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 `gvfs cache-server --get` to see the current cache server.
+
+Run `gvfs cache-server --list` to see the available cache server URLs.
+
+Run `gvfs cache-server --set=<url>` to set your cache server to `<url>`.
+
+### System-wide Config
+
+The `gvfs config` command allows customizing some behavior.
+
+1. Set system-wide config settings using `gvfs config <key> <value>`.
+2. View existing settings with `gvfs config --list`.
+3. Remove an existing setting with `gvfs config --delete <key>`.
+
+The `usn.updateDirectories` config option, when `true`, will update the
+[USN journal entries](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/fsutil-usn)
+of directories when the names of subdirectories or files are modified,
+even if the directory is still only in a "projected" state. This can be
+particularly important when using incremental build systems such as
+microsoft/BuildXL. However, there is a 10-15% performance penalty on some
+Git commands when this option is enabled.
+
+The `gvfs config` command is also used for customizing the feed used for
+VFS for Git upgrades. This is so large teams can bundle a custom installer
+or other tools along with VFS for Git upgrades.