chore(gitea): regenerate the flat content mirror after the ADR-0020 retrofit
Generated output, not authored content: scripts/sync-plugin-content.sh --all. Claude Code has no .apm/ awareness, so this compiled mirror must track .apm/ or the check-plugin-content-sync pre-push hook reports drift. Deferred to a single commit at the end of the wave on purpose. sync_dir runs rm -rf before every copy, so running it while seven agents were editing the same plugin would have raced them; agents were told not to sync for that reason. Refs #99
This commit is contained in:
46
plugins/gitea/skills/gitea-files/references/reading.md
Normal file
46
plugins/gitea/skills/gitea-files/references/reading.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
---
|
||||
|
||||
# Reading files, directories and trees
|
||||
|
||||
All three read calls select what to read with `ref` — a branch name, tag, or commit SHA. On
|
||||
`get_repository_tree` the same value goes in `tree_sha` despite the name.
|
||||
|
||||
## Single file
|
||||
|
||||
`get_file_contents(owner, repo, ref, path)`.
|
||||
|
||||
The response carries the file's `sha` at the **top level**, not nested under `content`. That field
|
||||
is the write-ready SHA, so capture it whenever a write may follow. Content comes back
|
||||
base64-encoded — decode it. Pass `withLines: true` only when you need numbered lines to quote
|
||||
specific lines back to the user; omit it for a normal content fetch.
|
||||
|
||||
## One directory level
|
||||
|
||||
`get_dir_contents(owner, repo, ref, path)` returns the immediate entries only — name, path, type,
|
||||
size. No recursion, no content, no `sha`.
|
||||
|
||||
## Whole repository tree
|
||||
|
||||
`get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk
|
||||
subdirectories in one call.
|
||||
|
||||
The response sets `truncated: true` when one page does not hold every entry. Page through with
|
||||
`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`.
|
||||
|
||||
## Neither listing is a SHA source for a write
|
||||
|
||||
`get_dir_contents` entries carry no `sha` at all. `get_repository_tree` entries do carry a blob or
|
||||
tree hash, but reaching it costs an extra round trip and returns no content. `get_file_contents` is
|
||||
the canonical path for a write's SHA: one call returns the decoded content and the write-ready
|
||||
`sha` together.
|
||||
|
||||
## A 404 that is really a 403
|
||||
|
||||
These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer
|
||||
an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A
|
||||
404 on a path you are confident about is a scope problem until proven otherwise — check the token's
|
||||
configured scopes before concluding the file or directory does not exist.
|
||||
Reference in New Issue
Block a user