Diff options
| author | Bryce Kwon <bryce@brycekwon.com> | |
|---|---|---|
| committer | Bryce Kwon <bryce@brycekwon.com> | |
| commit | ||
| parent | ||
| tree | ||
| download | ||
Document how cgit urls are built
| -rw-r--r-- | README.txt | 65 |
1 file changed, 65 insertions, 0 deletions
@@ -99,6 +99,71 @@ lighttpd live in `custom/servers/`, each explaining how that server routes requests to the binary and serves the static assets off disk. +URLs and query parameters +------------------------- + +cgit serves every page from one CGI program, so a url names the repository, the +page and a path inside that page. There are two forms and they carry the same +information. With virtual-root set, a request is a path, written as +/<repo>/<page>/<path> with anything else as a query string. Without it, the +whole request lives in the query string as ?url=<repo>/<page>/<path>, which is +the form the test suite uses. In the path form the first extra argument opens +the query string with a question mark, and in the url= form it continues the +existing one with an ampersand, which is why links in the two forms are spelled +differently. + +The page name is the second element and is one of about, atom, blame, blob, +commit, diff, log, patch, plain, rawdiff, refs, snapshot, stats, summary, tag or +tree. Leaving it out gives the repository summary, and leaving the repository +out as well gives the index of repositories. Everything after the page name is +the path argument, so /demo/tree/src/main.c asks for the tree page at +src/main.c. A repository whose name contains a character that is special in a +url has it percent-encoded, and a plus sign has to be written %2b because a bare +plus decodes to a space. + +These parameters are accepted, all of them optional. + + url repository, page and path in one value, used instead of the + path form + h the branch or ref to read, defaulting to the repository default + id pin the page to one commit or object, which every page that + shows history honours + id2 the second object for a diff, so id and id2 name the two sides + ofs offset into a paged listing, used by log, refs and stats + path restrict the page to one path, equivalent to the trailing path + q the search term + qt what to search, one of grep, author, committer or range + s sort key on the index and refs pages + showmsg show full commit messages in a log listing + period the statistics window, one of w, m, q or y + dt diff type, selecting unified, side by side or raw + ss shorthand for the side by side diff + all include every ref rather than one branch, used by atom + context lines of context in a diff + ignorews ignore whitespace when diffing + follow follow a single path across renames in a log + +A few endpoints are not ordinary pages. The snapshot page takes a filename +rather than a ref, so /demo/snapshot/demo-1.0.tar.gz names both the ref and the +archive format through the suffix, and the formats on offer are set by the +snapshots option. The plain page serves a blob as its own bytes under headers +that stop a browser treating repository content as markup. The atom page is a +feed rather than a page and accepts h, path and all. The clone endpoints under +info and objects implement the dumb HTTP protocol and are only present when http +clone is enabled. + +Some worked examples, in the url= form. + + ?url= the repository index + ?url=demo summary for the demo repository + ?url=demo/log&h=next log of the next branch + ?url=demo/log&qt=author&q=alice commits authored by alice + ?url=demo/tree/src&h=v1.0 the src directory at tag v1.0 + ?url=demo/commit&id=HEAD~3 one commit, pinned + ?url=demo/diff&id=main&id2=next diff between two branches + ?url=demo/plain/README.md the raw bytes of one file + ?url=demo/atom&h=main the commit feed for a branch + Runtime configuration --------------------- |