docs/cli: Add missing doc pages for src-cli commands - #1889
Merged
marcleblanc2 merged 2 commits intoSep 11, 2026
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
marcleblanc2
changed the title
marcleblanc2
changed the title
pjlast
approved these changes
Sep 11, 2026
marcleblanc2
enabled auto-merge (squash)
September 11, 2026 01:49
marcleblanc2
added a commit
that referenced
this pull request
Sep 11, 2026
## Why The docs sync from `sourcegraph/sourcegraph` ([`doc/_generated.push.sh`](https://github.com/sourcegraph/sourcegraph/blob/main/doc/_generated.push.sh)) does `cp -R -L doc/cli/** _clone/docs/cli/` — it only adds and updates pages, never deletes. So when a command is removed from src-cli, its reference page lingers here forever. Replaying the sync against `main` shows zero drift in the 62 generated pages, but 36 files under `docs/cli/references/` are never written by it. This PR deletes the 28 that are stale. No redirects are added; none of these pages are linked from anywhere in the site. ## Removed (28 files) **Command removed from src-cli** | Pages | Removal | |---|---| | `extensions/{index,copy,delete,get,list,publish}` | sourcegraph/src-cli#1173 (extensions platform sunset) | | `lsif` | sourcegraph/src-cli#1147 (→ `src code-intel upload`) | | `scout` | sourcegraph/src-cli#1196 | | `sbom`, `signature` | sourcegraph/src-cli#1273 (SBOMs/signatures no longer published as of 7.0.2852; the how-tos already carry deprecation notices) | | `admin` | sourcegraph/src-cli#1309 (built for the appliance, which never launched) | | `validate` | sourcegraph/src-cli#1310 | **Command never shipped** `prompts` + 13 subcommand pages (#1155) documented sourcegraph/src-cli#1168, which was closed unmerged. **Stale duplicates shadowing generated pages** `auth.mdx` and `codeowners.mdx` collide with `auth/index.mdx` / `codeowners/index.mdx`: contentlayer flattens both to `cli/references/auth`, and `allPosts.find` returned the stale flat file. After this change `/cli/references/auth` and `/cli/references/codeowners` render the generated group pages (verified with `contentlayer build`). ## Kept `search-jobs/{cancel,create,delete,get,list,logs,restart,results}` — the subcommands exist, but `src doc` only emits a single `search-jobs.md` because `searchJobsCommands` isn't in the `commanders` map in [`cmd/src/doc.go`](https://github.com/sourcegraph/src-cli/blob/main/cmd/src/doc.go#L59-L66). Fix belongs upstream. ## Verification - `npx tsc --noEmit` passes - `npx contentlayer build` generates 493 docs; `cli/references/auth` and `cli/references/codeowners` now resolve to the `index.mdx` files - No remaining links to the deleted slugs anywhere in `docs/` or `src/` ## Follow-up (upstream) To stop this recurring, `_generated.push.sh` should mirror `docs/cli/references/` (delete-then-copy) instead of copying over it. Done in sourcegraph/sourcegraph#15529 (merge after sourcegraph/sourcegraph#15528 and #1889). ## Amp threads - [Stale command docs](https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1) Co-authored-by: Amp <amp@ampcode.com>
…; list all commands in index Pre-seeds the output of the fixed `src doc` generator (sourcegraph/src-cli#1375) so the CLI reference is correct now rather than after the next src-cli release and docs sync: - index.mdx lists all 20 top-level commands again (was only the 8 urfave/cli ones since src-cli#1304). - debug/, snapshot/: new index + subcommand pages (9 files). - search-jobs/: new index; the 8 hand-written subcommand pages are replaced by the generated equivalents (same usage text, plus a flags table). - Delete the flat debug.mdx, search-jobs.mdx, snapshot.mdx. The sync job never deletes, and these would shadow the new <group>/index.mdx in contentlayer routing. Files were produced with the same md2mdx conversion the sync uses; the sync/generated-docs PR that follows sourcegraph/sourcegraph#15528 should be a no-op for these paths. Part of https://linear.app/sourcegraph/issue/FE-502 Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1
Teams were removed in Sourcegraph 7.0; src-cli#1376 removes the command. No redirect, per the same call as #1886. Part of https://linear.app/sourcegraph/issue/FE-502 Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1 Co-authored-by: Amp <amp@ampcode.com>
marcleblanc2
force-pushed
the
cli-refs/search-jobs-debug-snapshot-subcommand-pages
branch
from
September 11, 2026 02:06
77deb9c to
322141e
Compare
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
CSpell found 3 spelling error(s) on lines added by this PR. Please correct them, or add them to cspell-allow-list.txt if they are correct.
|
|
||
| $ src debug server -c foo -o debug.zip | ||
|
|
||
| $ src -v debug server --no-configs -c ViktorVaughn -o foo.zip |
There was a problem hiding this comment.
Viktor is not in the dictionary.
Did you mean Victor?
Suggested change
| $ src -v debug server --no-configs -c ViktorVaughn -o foo.zip | |
| $ src -v debug server --no-configs -c VictorVaughn -o foo.zip |
Please correct the spelling, or add the word to cspell-allow-list.txt if it is correct.
| codeinsights: | ||
| # same as above | ||
|
|
||
| See the pgdump.Targets type for more details. |
There was a problem hiding this comment.
pgdump is not in the dictionary.
Did you mean pump?
Suggested change
| See the pgdump.Targets type for more details. | |
| See the pump.Targets type for more details. |
Please correct the spelling, or add the word to cspell-allow-list.txt if it is correct.
| codeinsights: | ||
| # same as above | ||
|
|
||
| See the pgdump.Targets type for more details. |
There was a problem hiding this comment.
pgdump is not in the dictionary.
Did you mean pump?
Suggested change
| See the pgdump.Targets type for more details. | |
| See the pump.Targets type for more details. |
Please correct the spelling, or add the word to cspell-allow-list.txt if it is correct.
marcleblanc2
deleted the
cli-refs/search-jobs-debug-snapshot-subcommand-pages
branch
September 11, 2026 02:09
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of FE-502. Step 4 of 4 in a cross-repo stack, but mergeable now — it pre-seeds what the generated-docs sync will eventually write, so the live reference gets fixed without waiting on a src-cli release.
Why
The
srcCLI reference is generated bysrc docand synced here by sourcegraph/sourcegraph'ssync/generated-docsjob. Two generator bugs (fixed in sourcegraph/src-cli#1375) left this reference incomplete:search-jobs,debugandsnapshotwere never registered in the generator'scommandersmap, so each is a single page with only the group help; their 16 subcommands have no reference pages. (The 8search-jobs/*.mdxpages here were hand-written by Travis Lyons in May 2025 to paper over this; nothing links to them.)index.mdxlists only the 8 urfave/cli commands (abc,api,auth,codeowners,login,orgs,users,version) —batch,repos,search,config, etc. are missing from https://sourcegraph.com/docs/cli/references today.What
index.mdx: lists all 19 top-level commands.debug/{index,compose,kube,server}.mdx,snapshot/{index,databases,restore,summary,test,upload}.mdx: new.search-jobs/index.mdx: new;search-jobs/{cancel,create,delete,get,list,logs,restart,results}.mdx: hand-written pages replaced by generated ones (same usage text, plus a flags table; the<p className="subtitle">blurbs go away since the generator doesn't emit them).debug.mdx,search-jobs.mdx,snapshot.mdx.teams.mdxand droppedteamsfromindex.mdx: teams were removed in Sourcegraph 7.0 and chore: Remove deprecatedsrc teamscommands src-cli#1376 removes the command, so the generator no longer emits this page. No redirect (same call as docs/cli: Remove doc pages for removed src-cli commands #1886). The sync job never deletes files, and in contentlayer routing a flatfoo.mdxshadowsfoo/index.mdx(the same bug docs/cli: Remove doc pages for removed src-cli commands #1886 fixed forauth.mdx/codeowners.mdx), so these have to go by hand for the new index pages to be reachable.Content was produced by running the patched generator (src-cli
main+ #1375) and the sametools/md2mdxconversion the sync uses, so the sync PR that follows sourcegraph/sourcegraph#15528 should be a no-op for these paths.No redirects: the three deleted URLs (
/cli/references/{debug,search-jobs,snapshot}) keep resolving, now to the new index pages.Stack
src teamscommands src-cli#1376 (stacked) — removesrc teams; fix/help: Generate help command list from registered commands src-cli#1377 (stacked) —src helpgenerated from registered commands, tests help == docsOUTPUT_FILES+ regenerate (draft until 2)docs/cli/references/so removed commands disappear automatically (merge after 3 and this PR)Related: #1886 (removed 28 stale pages for commands that no longer exist).
Test plan
npx contentlayer build→ 528 documents; routes resolve to the intended files:plus the 16 subcommand routes. (The
ERR_INVALID_ARG_TYPE/clipanion stack trace during the build is pre-existing onmain.)Amp threads