sourcegraph · emidoots · May 8, 2020 · May 7, 2020 · May 7, 2020 · May 7, 2020
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,34 @@
+## Development
+
+If you want to develop the CLI, clone the repository and build/install it with `go install`
+
+```
+cd src-cli/
+go install ./cmd/src
+```
+
+## Releasing
+
+1.  Find the latest version (either via the releases tab on GitHub or via git tags) to determine which version you are releasing.
+2.  `VERSION=9.9.9 ./release.sh` (replace `9.9.9` with the version you are releasing)
+3.  Travis will automatically perform the release. Once it has finished, **confirm that the curl commands fetch the latest version above**.
+4.  Update the `MinimumVersion` constant in the [src-cli package](https://github.com/sourcegraph/sourcegraph/tree/master/internal/src-cli/consts.go).
+
+### Patch releases
+
+If a backwards-compatible change is made _after_ a backwards-incompatible one, the backwards-compatible one should be re-released to older instances that support it.
+
+A Sourcegraph instance returns the highest patch version with the same major and minor version as `MinimumVersion` as defined in the instance. Patch versions are reserved solely for non-breaking changes and minor bug fixes. This allows us to dynamically release fixes for older versions of `src-cli` without having to update the instance.
+
+To release a bug fix or a new feature that is backwards compatible with one of the previous two minor version of Sourcegraph, cherry-pick the changes into a patch branch and re-releases with a new patch version. 
+
+For example, suppose we have the the recommended versions.
+
+| Sourcegraph version | Recommended src-cli version |
+| ------------------- | --------------------------- | 
+| `3.100`             | `3.90.5`                    |
+| `3.99`              | `3.85.7`                    |
+
+If a new feature is added to a new `3.91.6` release of src-cli and this change requires only features available in Sourcegraph `3.99`, then this feature should also be present in a new `3.85.8` release of src-cli. Because a Sourcegraph instance will automatically select the highest patch version, all non-breaking changes should increment only the patch version. 
+
+Note that if instead the recommended src-cli version for Sourcegraph `3.99` was `3.90.4` in the example above, there is no additional step required, and the new patch version of src-cli will be available to both Sourcegraph versions.
diff --git a/README.md b/README.md
@@ -1,186 +1,117 @@
-# Sourcegraph CLI [![Build Status](https://travis-ci.org/sourcegraph/src-cli.svg)](https://travis-ci.org/sourcegraph/src-cli) [![Go Report Card](https://goreportcard.com/badge/sourcegraph/src-cli)](https://goreportcard.com/report/sourcegraph/src-cli)
+# [Sourcegraph](https://sourcegraph.com) CLI [![Build Status](https://travis-ci.org/sourcegraph/src-cli.svg)](https://travis-ci.org/sourcegraph/src-cli) [![Go Report Card](https://goreportcard.com/badge/sourcegraph/src-cli)](https://goreportcard.com/report/sourcegraph/src-cli)
 
-<img src="https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png" width=450 align=right>
+<img src="https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png" width=500 align=right>
 
-**Quick links**:
-- [Installation](#installation)
-- [Setup](#setup) ([Authentication](#authentication))
-- [Usage](#usage)
+`src` is a command line interface to Sourcegraph:
 
-The Sourcegraph `src` CLI provides access to [Sourcegraph](https://sourcegraph.com) via a command-line interface.
+- **Search & get results in your terminal**
+- **Search & get JSON** for programmatic consumption
+- Make **GraphQL API requests** with auth easily & get JSON back fast
+- Execute **[campaign actions](https://docs.sourcegraph.com/user/campaigns)**
+- **Manage & administrate** repositories, users, and more
+- **Easily convert src-CLI commands to equivalent curl commands**, just add --get-curl!
 
-It currently provides the ability to:
-
-- **Execute search queries** from the command line and get nice colorized output back (or JSON, optionally).
-- **Execute GraphQL queries** against a Sourcegraph instance, and get JSON results back (`src api`).
-  - You can provide your API access token via an environment variable or file on disk.
-  - You can easily convert a `src api` command into a curl command with `src api -get-curl`.
-- **Manage repositories, users, and organizations** using the `src repos`, `src users`, and `src orgs` commands.
-- **Execute campaign actions** as part of [Sourcegraph campaigns](https://docs.sourcegraph.com/user/campaigns)
-
-If there is something you'd like to see Sourcegraph be able to do from the CLI, let us know! :)
+**Note:** Using Sourcegraph 3.12 or earlier? [See the older README](https://github.com/sourcegraph/src-cli/tree/3.11.2).
 
 ## Installation
 
-For Sourcegraph 3.13 and newer, the preferred method of installation is to ask _your_ Sourcegraph instance for the latest compatible version. To do this, replace `https://sourcegraph.com` in the commands below with the address of your instance.
-
-For Sourcegraph 3.12 and older, run the following commands verbatim (against sourcegraph.com) or install from one of the published [releases on GitHub](https://github.com/sourcegraph/src-cli/releases).
-
-```
-https://github.com/sourcegraph/src-cli/releases/download/{version}/{binary}
-```
+Binary downloads are available on the [releases tab](https://github.com/sourcegraph/src-cli/releases), and through Sourcegraph.com. _If the latest version does not work for you,_ consider using the version compatible with your Sourcegraph instance instead.
 
-#### Requirements
+### Installation: Mac OS
 
-If you want to use the `src action exec` functionality (see [Sourcegraph campaigns](https://docs.sourcegraph.com/user/campaigns) docs and `src action exec -h`), make sure that `git` is installed and accessible by `src`.
-
-#### Mac OS
+#### Latest version
 
 ```bash
-# Sourcraph 3.13 and newer:
-curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
-chmod +x /usr/local/bin/src
-
-# Sourcraph 3.12 and older:
 curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
 chmod +x /usr/local/bin/src
 ```
 
-or use `brew` to get the newest version:
+or
 
-```
+```bash
 brew install sourcegraph/src-cli/src-cli
 ```
 
-#### Linux
+#### Version compatible with your Sourcegraph instance
 
-```bash
-# Sourcraph 3.13 and newer:
-curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
-chmod +x /usr/local/bin/src
+Replace `sourcegraph.example.com` with your Sourcegraph instance URL:
 
-# Sourcraph 3.12 and older:
-curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
+```bash
+curl -L https://sourcegraph.example.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
 chmod +x /usr/local/bin/src
 ```
 
-#### Windows
-
-**NOTE:** Windows support is still rough around the edges, but is available. If you encounter issues, please let us know by filing an issue :)
-
-Run in PowerShell as administrator:
+### Installation: Linux
 
-```powershell
-New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'
+#### Latest version
 
-# Sourcegraph 3.13 and newer:
-Invoke-WebRequest https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
-# Sourcegraph 3.12 and older:
-Invoke-WebRequest https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
-
-[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
-$env:Path += ';C:\Program Files\Sourcegraph'
+```bash
+curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
+chmod +x /usr/local/bin/src
 ```
 
-Or manually:
-
-- Download the latest src_windows_amd64.exe:
-  - Sourcegraph 3.13 and newer: https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe
-  - Sourcegraph 3.12 and older: https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe
-- Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe`
-- Add that directory to your system path to access it from any command prompt
+#### Version compatible with your Sourcegraph instance
 
-#### Renaming `src` (optional)
+Replace `sourcegraph.example.com` with your Sourcegraph instance URL:
 
-If you have a naming conflict with the `src` command, such as a Bash alias, you can rename the static binary. For example, on Linux / Mac OS:
-
-```sh
-mv /usr/local/bin/src /usr/local/bin/sourcegraph-cli
+```bash
+curl -L https://sourcegraph.example.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
+chmod +x /usr/local/bin/src
 ```
 
-You can then invoke it via `sourcegraph-cli`.
+### Installation: Windows
 
-## Setup
+See [Sourcegraph CLI for Windows](WINDOWS.md).
 
-To use `src` with your own Sourcegraph instance set the `SRC_ENDPOINT` environment variable:
+## Setup with your Sourcegraph instance
 
-```sh
-SRC_ENDPOINT=https://sourcegraph.example.com src search
-```
+### Via environment variables
 
-Or via the configuration file (`~/src-config.json`):
+Point `src` to your instance and access token using environment variables:
 
 ```sh
-{"endpoint": "https://sourcegraph.example.com"}
+SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src search 'foobar'
 ```
 
-### Authentication
+### Via global configuration file
 
-Some Sourcegraph instances will be configured to require authentication. You can do so via the environment variable `SRC_ACCESS_TOKEN`:
+Create a `$HOME/src-config.json` with:
 
 ```sh
-SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src ...
+{"endpoint": "https://sourcegraph.example.com", "accessToken": "secret"}
 ```
 
-Or via the configuration file (`~/src-config.json`):
+Then `src search 'foobar'` and other commands will automatically use that configuration!
 
-```sh
-{"accessToken": "secret", "endpoint": "https://sourcegraph.example.com"}
-```
+### Where to get an access token
 
-See `src -h` for more information on specifying access tokens.
-
-To acquire the access token, visit your Sourcegraph instance (or https://sourcegraph.com), click your username in the top right to open the user menu, select **Settings**, and then select **Access tokens** in the left hand menu.
+Visit your Sourcegraph instance (or https://sourcegraph.com), click your username in the top right to open the user menu, select **Settings**, and then select **Access tokens** in the left hand menu.
 
 ## Usage
 
 `src` provides different subcommands to interact with different parts of Sourcegraph:
 
- - `search` - search for results on the configured Sourcegraph instance
- - `api` - interacts with the Sourcegraph GraphQL API
- - `repos` (alias: `repo`) - manages repositories
- - `users` (alias: `user`) - manages users
- - `orgs` (alias: `org`) - manages organizations
- - `config` - manages global, org, and user settings
- - `extsvc` - manages external services
- - `extensions` (alias: `ext`) - manages extensions
- - `actions` - runs [campaign actions](https://docs.sourcegraph.com/user/campaigns/actions)to generate patch sets
- - `campaigns` - manages [campaigns](https://docs.sourcegraph.com/user/campaigns)
- - `lsif` - manages LSIF data
- - `version` - display and compare the src-cli version against the recommended version of the configured Sourcegraph instance
+ - `src search` - perform searches and get results in your terminal or as JSON
+ - `src actions` - run [campaign actions](https://docs.sourcegraph.com/user/campaigns/actions) to generate patch sets
+ - `src api` - run Sourcegraph GraphQL API requests
+ - `src campaigns` - manages [campaigns](https://docs.sourcegraph.com/user/campaigns)
+ - `src repos` - manage repositories
+ - `src users` - manage users
+ - `src orgs` - manages organization
+ - `src config` - manage global, org, and user settings
+ - `src extsvc` - manage external services (repository configuration)
+ - `src extensions` - manage extensions
+ - `src lsif` - manages LSIF data
+ - `src version` - check version and guaranteed-compatible version for your Sourcegraph instance
 
 Run `src -h` and `src <subcommand> -h` for more detailed usage information.
 
-## Development
+#### Optional: Renaming `src`
 
-If you want to develop the CLI, you can install it with `go get`:
+If you have a naming conflict with the `src` command, such as a Bash alias, you can rename the static binary. For example, on Linux / Mac OS:
 
+```sh
+mv /usr/local/bin/src /usr/local/bin/src-cli
 ```
-go get -u github.com/sourcegraph/src-cli/cmd/src
-```
-
-## Releasing
-
-1.  Find the latest version (either via the releases tab on GitHub or via git tags) to determine which version you are releasing.
-2.  `VERSION=9.9.9 ./release.sh` (replace `9.9.9` with the version you are releasing)
-3.  Travis will automatically perform the release. Once it has finished, **confirm that the curl commands fetch the latest version above**.
-4.  Update the `MinimumVersion` constant in the [src-cli package](https://github.com/sourcegraph/sourcegraph/tree/master/internal/src-cli/consts.go).
-
-### Patch releases
-
-If a backwards-compatible change is made _after_ a backwards-incompatible one, the backwards-compatible one should be re-released to older instances that support it.
-
-A Sourcegraph instance returns the highest patch version with the same major and minor version as `MinimumVersion` as defined in the instance. Patch versions are reserved solely for non-breaking changes and minor bug fixes. This allows us to dynamically release fixes for older versions of `src-cli` without having to update the instance.
-
-To release a bug fix or a new feature that is backwards compatible with one of the previous two minor version of Sourcegraph, cherry-pick the changes into a patch branch and re-releases with a new patch version. 
-
-For example, suppose we have the the recommended versions.
-
-| Sourcegraph version | Recommended src-cli version |
-| ------------------- | --------------------------- | 
-| `3.100`             | `3.90.5`                    |
-| `3.99`              | `3.85.7`                    |
-
-If a new feature is added to a new `3.91.6` release of src-cli and this change requires only features available in Sourcegraph `3.99`, then this feature should also be present in a new `3.85.8` release of src-cli. Because a Sourcegraph instance will automatically select the highest patch version, all non-breaking changes should increment only the patch version. 
 
-Note that if instead the recommended src-cli version for Sourcegraph `3.99` was `3.90.4` in the example above, there is no additional step required, and the new patch version of src-cli will be available to both Sourcegraph versions.
+You can then invoke it via `src-cli`.
diff --git a/WINDOWS.md b/WINDOWS.md
@@ -0,0 +1,47 @@
+# Sourcegraph CLI for Windows
+
+**Note:** Windows support is still rough around the edges. If you encounter issues, please let us know by filing an issue.
+
+## Installation
+
+### Latest version
+
+### Install via PowerShell
+
+Run in PowerShell as administrator:
+
+```powershell
+New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'
+
+Invoke-WebRequest https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
+
+[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
+$env:Path += ';C:\Program Files\Sourcegraph'
+```
+
+#### Install manually
+
+1. Download the latest [src_windows_amd64.exe](https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe)
+2. Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe`
+3. Add that directory to your system PATH to access it from any command prompt
+
+### Version compatible with your Sourcegraph instance
+
+### Install via PowerShell
+
+Run in PowerShell as administrator, but replace `sourcegraph.example.com` with your Sourcegraph instance URL:
+
+```powershell
+New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'
+
+Invoke-WebRequest https://sourcegraph.example.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
+
+[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
+$env:Path += ';C:\Program Files\Sourcegraph'
+```
+
+#### Install manually
+
+1. Download the latest src_windows_amd64.exe from your Sourcegraph instance at e.g. https://sourcegraph.example.com/.api/src-cli/src_windows_amd64.exe (replace sourcegraph.example.com with your Sourcegraph instance URL)
+2. Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe`
+3. Add that directory to your system PATH to access it from any command prompt