From e3c8b1ef6cf90ec58e18bd405cce8857d67af0a1 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:08:32 -0600 Subject: [PATCH] docs/readme: drop the Sourcegraph 3.12 note and refresh stale content The README still pointed readers of Sourcegraph 3.12 or earlier at a 3.11.2-era README, listed a `src extensions` command that no longer exists, and left out commands that have shipped since. Install examples used 3.x versions and only offered amd64 downloads, and the Go Report Card badge now renders "retired" because that service has been sunset. Remove the 3.12 note and the Go Report Card badge. Rebuild the subcommand list from `src help`, sorted alphabetically: drop `extensions`, add `abc`, `codeowners`, `debug`, `lsp`, `search-jobs`, and `snapshot`. Use 8.1.2687 in the versioned install examples and drop the repeated version mentions in the surrounding prose. Default the macOS download to `src_darwin_arm64`, note the `src_linux_arm64` build, fix the `docs/batch_changes` redirect, drop the dead-to-bots computerhope link and the stale Homebrew 3.43.2 note, and tighten the Installation and Docker wording. Point the `src config` error message at the README's "Connect to your Sourcegraph instance" heading; its `#authentication` anchor no longer exists. Add `.markdownlint-cli2.jsonc` so the README lints clean: prose here is not hard-wrapped, the screenshot and the anchor other repos link to need inline HTML, and the per-OS install headings repeat on purpose. Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-01a1a3a9-87bc-743d-b475-c96ace107ed5 --- .markdownlint-cli2.jsonc | 10 +++++ README.md | 79 +++++++++++++++++++++------------------- cmd/src/config.go | 2 +- 3 files changed, 52 insertions(+), 39 deletions(-) create mode 100644 .markdownlint-cli2.jsonc diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..95ef757ff0 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,10 @@ +{ + "config": { + // Prose in this repo is not hard-wrapped. + "MD013": false, + // "Latest version" and friends repeat under each OS heading. + "MD024": { "siblings_only": true }, + // The README floats a screenshot right and keeps an anchor that other repos link to. + "MD033": { "allowed_elements": ["img", "a"] } + } +} diff --git a/README.md b/README.md index 37100691a3..97e669a5c6 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,26 @@ -# [Sourcegraph](https://sourcegraph.com) CLI [![Build Status](https://github.com/sourcegraph/src-cli/workflows/Go%20CI/badge.svg)](https://github.com/sourcegraph/src-cli/actions?query=workflow%3A%22Go+CI%22) [![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://github.com/sourcegraph/src-cli/workflows/Go%20CI/badge.svg)](https://github.com/sourcegraph/src-cli/actions?query=workflow%3A%22Go+CI%22) - +src search results in a terminal `src` is a command line interface to Sourcegraph: - **Search & get results in your terminal** - **Search & get JSON** for programmatic consumption - Make **GraphQL API requests** with auth easily & get JSON back fast -- Execute **[batch changes](https://sourcegraph.com/docs/batch_changes)** +- Execute **[batch changes](https://sourcegraph.com/docs/batch-changes)** - **Manage & administrate** repositories, users, and more - **Easily convert src-CLI commands to equivalent curl commands**, just add --get-curl! -**Note:** Using Sourcegraph 3.12 or earlier? [See the older README](https://github.com/sourcegraph/src-cli/tree/3.11.2). - ## Installation -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. +Download the latest version from the [releases page](https://github.com/sourcegraph/src-cli/releases), or from Sourcegraph.com using the commands below. If the latest version does not work with your Sourcegraph instance, download the version compatible with your Sourcegraph instance, as shown below. -### Installation: Mac OS +### Installation: macOS #### Latest version ```bash -curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src +curl -L https://sourcegraph.com/.api/src-cli/src_darwin_arm64 -o /usr/local/bin/src chmod +x /usr/local/bin/src ``` @@ -43,24 +41,22 @@ npm install -g @sourcegraph/src Replace `sourcegraph.example.com` with your Sourcegraph instance URL: ```bash -curl -L https://sourcegraph.example.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src +curl -L https://sourcegraph.example.com/.api/src-cli/src_darwin_arm64 -o /usr/local/bin/src chmod +x /usr/local/bin/src ``` -or, if you know the specific version to target, for example 3.43.2: +or, if you know the specific version to target: ```bash -brew install sourcegraph/src-cli/src-cli@3.43.2 +brew install sourcegraph/src-cli/src-cli@8.1.2687 ``` or with npm/npx: ```bash -npx @sourcegraph/src@3.43.2 version +npx @sourcegraph/src@8.1.2687 version ``` -> Note: Versioned formulas are available on Homebrew for Sourcegraph versions 3.43.2 and later. - ### Installation: Linux #### Latest version @@ -70,6 +66,8 @@ curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/s chmod +x /usr/local/bin/src ``` +On an ARM host, replace `src_linux_amd64` with `src_linux_arm64`. + or with npm: ```bash @@ -85,10 +83,10 @@ curl -L https://sourcegraph.example.com/.api/src-cli/src_linux_amd64 -o /usr/loc chmod +x /usr/local/bin/src ``` -or, with npm/npx, if you know the specific version to target, for example 3.43.2: +or, with npm/npx, if you know the specific version to target: ```bash -npx @sourcegraph/src@3.43.2 version +npx @sourcegraph/src@8.1.2687 version ``` ### Installation: Windows @@ -97,7 +95,7 @@ See [Sourcegraph CLI for Windows](WINDOWS.md). ### Installation: Docker -`sourcegraph/src-cli` is published to Docker Hub. You can use the `latest` tag or a specific version such as `3.43`. To see all versions view [sourcegraph/src-cli tags](https://hub.docker.com/r/sourcegraph/src-cli/tags). +The [`sourcegraph/src-cli`](https://hub.docker.com/r/sourcegraph/src-cli/tags) image on Docker Hub is tagged with `latest` and with each release version. ```bash docker run --rm=true sourcegraph/src-cli:latest search 'hello world' @@ -119,7 +117,7 @@ For PowerShell on Windows: $env:SRC_ENDPOINT = 'https://sourcegraph.example.com' ``` -For convenience, add this environment variable to your terminal profile or system environment variables. On Mac OS and Linux, the terminal profile is typically `~/.bash_profile` for Bash or `~/.zprofile` for Zsh. On Windows, you can add it through the *System Properties* window. See [these instructions](https://www.computerhope.com/issues/ch000549.htm) for details. +For convenience, add this environment variable to your terminal profile or system environment variables. On macOS and Linux, the terminal profile is typically `~/.zprofile` for Zsh or `~/.bash_profile` for Bash. On Windows, you can add it through the *System Properties* window. If `SRC_ENDPOINT` is not set, `src` defaults to `https://sourcegraph.com`. @@ -169,27 +167,32 @@ Is your Sourcegraph instance behind a custom auth proxy? See [auth proxy configu `src` provides different subcommands to interact with different parts of Sourcegraph: - - `src login` - authenticate to a Sourcegraph instance with your user credentials - - `src auth` - print the active authentication token or authorization header - - `src search` - perform searches and get results in your terminal or as JSON - - `src api` - run Sourcegraph GraphQL API requests - - `src batch` - execute and manage [batch changes](https://sourcegraph.com/docs/batch_changes) - - `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 code-intel` - manages Code Intelligence data - - `src serve-git` - serves your local git repositories over HTTP for Sourcegraph to pull - - `src version` - check version and guaranteed-compatible version for your Sourcegraph instance +- `src abc` - manage agentic batch changes +- `src api` - run Sourcegraph GraphQL API requests +- `src auth` - print the active authentication token or authorization header +- `src batch` - execute and manage [batch changes](https://sourcegraph.com/docs/batch-changes) +- `src code-intel` - manage code intelligence data +- `src codeowners` - manage ingested code ownership data +- `src config` - manage global, org, and user settings +- `src debug` - gather and bundle debug data from a Sourcegraph deployment for troubleshooting +- `src extsvc` - manage external services (repository configuration) +- `src login` - authenticate to a Sourcegraph instance with your user credentials +- `src lsp` - run a Language Server Protocol server that proxies requests to Sourcegraph code intelligence +- `src orgs` - manage organizations +- `src repos` - manage repositories +- `src search` - perform searches and get results in your terminal or as JSON +- `src search-jobs` - manage search jobs +- `src serve-git` - serve your local git repositories over HTTP for Sourcegraph to pull +- `src snapshot` - manage snapshots of Sourcegraph instance databases (experimental) +- `src users` - manage users +- `src version` - display and compare the `src` version against the recommended version for your Sourcegraph instance Run `src -h` and `src -h` for more detailed usage information. You can also read the [usage docs for the latest version of `src-cli`](https://sourcegraph.com/docs/cli/references) online. -#### Optional: Renaming `src` +### Optional: Renaming `src` -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: +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 / macOS: ```sh mv /usr/local/bin/src /usr/local/bin/src-cli @@ -203,13 +206,13 @@ You can then invoke it via `src-cli`. ## Telemetry -`src` includes the operating system and architecture in the `User-Agent` header sent to Sourcegraph. For example, running `src` version 3.21.10 on an x86-64 Linux host will result in this header: +`src` includes the operating system and architecture in the `User-Agent` header sent to Sourcegraph. For example, running `src` on an x86-64 Linux host will result in this header: -``` -src-cli/3.21.10 linux amd64 +```text +src-cli/8.1.2687 linux amd64 ``` -To disable this and _only_ send the version, you can set `-user-agent-telemetry=false` for a single command, or set the `SRC_DISABLE_USER_AGENT_TELEMETRY` environment variable to any non-blank string. +To disable this and *only* send the version, you can set `-user-agent-telemetry=false` for a single command, or set the `SRC_DISABLE_USER_AGENT_TELEMETRY` environment variable to any non-blank string. As with other Sourcegraph telemetry, any collected data is only sent to Sourcegraph.com in aggregate form. diff --git a/cmd/src/config.go b/cmd/src/config.go index e6e7dfc937..898e1e5d1d 100644 --- a/cmd/src/config.go +++ b/cmd/src/config.go @@ -136,7 +136,7 @@ query ViewerUserID { } if result.CurrentUser == nil || result.CurrentUser.ID == "" { - return "", errors.New("unable to determine current user ID (see https://github.com/sourcegraph/src-cli#authentication)") + return "", errors.New("unable to determine current user ID (see https://github.com/sourcegraph/src-cli#connect-to-your-sourcegraph-instance)") } return result.CurrentUser.ID, nil }