docs: reframe around gh --attach and document the -- passthrough - #60
Draft
drogers0 wants to merge 3 commits into
Draft
docs: reframe around gh --attach and document the -- passthrough#60drogers0 wants to merge 3 commits into
drogers0 wants to merge 3 commits into
Conversation
The official CLI now attaches images and video with --attach, so the README can no longer open by saying the terminal has no answer for attachments. Lead instead with what the first-party flag does not cover — other file types, read-only repositories, a URL on its own, and download — and add a short table pointing readers at whichever tool fits. Documents the passthrough proposed in #58: files left of --, a gh invocation right of it, delegated to gh --attach when gh will take the job and handled locally when it will not. Covers the create exception, the capability probe, the reference rewriting that the local route needs, and the change to how a dash-leading filename is written now that -- marks the start of the gh command. Blocked by #58 and by the upstream release; nothing here is implemented yet.
Describe gh-image as the superset it is rather than as one of two options — the passthrough consumes gh --attach, so a table asking readers to choose between them was the wrong shape. Cut the routing rationale that had leaked into user-facing prose: which route a file takes, why a create is never delegated, and what a refusal costs are implementation concerns, not things a reader needs before running a command.
Send the common case upstream in a note near the top, then state the four things the flag does not cover as bullets rather than a run-on sentence. Release date and minimum gh version are placeholders until the release lands.
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
1 participant
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.
Warning
Blocked. Do not merge yet.
This documents functionality that does not exist. It describes the
--passthrough proposed in #58, which is unimplemented, and it compares againstgh --attach, which is merged upstream but not yet in anyghrelease — v2.98.0 predates the merge.Two things must land first: #58, and an upstream release carrying
--attach. Until then every command in the README's passthrough section fails.Draft of the documentation changes tracked in #59, written against the world where #58 has shipped.
README
The opening line was "GitHub has no public API for the attachment uploads its web UI accepts via drag-and-drop." Still true — cli/cli#9046 is labeled
blockedfor exactly that reason — but as a first sentence it implies the terminal has no answer, which stops being the case the moment--attachships. It now leads with what the tool does, then one line placing it as a superset of the first-party flag.Also: a Post it in one command section for the passthrough, replacing the old command-substitution example (kept below it, since it is still the better fit for a link that belongs somewhere other than an issue or PR); alt text in the usage examples; and one clause each in Authentication and How it works.
Skill
Step 2 leads with the single-command form and falls back to capturing the URL only when the reference belongs somewhere
ghwill not put it. That removes a read of the existing body for the common case.Architecture
CLI surface, a component section for the delegation and another for the rewriting, and a future-considerations note on what would let
createdelegate too. Routing rationale lives here rather than in the README.Two things worth deciding before this merges
--already means something. It currently terminates flag parsing so a filename beginning with-can be passed positionally. The passthrough claims the separator, so-name.pngbecomes./-name.png. Documented as written, but it is a behaviour change that #58 does not mention, and the alternative is a different separator.Placeholders to fill at release. The note near the top of the README carries
TBD-RELEASE-DATEandTBD-VERSION, which must be replaced with the realghrelease before this merges. Nothing here names agh-imageversion for the passthrough either, and the skill's--versionfloor is untouched.Closes #59 once unblocked.