diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000000..b998d02eb5 --- /dev/null +++ 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 index d2acb43d8c..9cd19e06b8 100644 --- 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) - + -**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:///.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:///.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:///.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:///.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 -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 new file mode 100644 index 0000000000..ba299b7437 --- /dev/null +++ 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