GitHubivarvong

ply

main
ply7 git calls31 ms27 KiB5 cachedprotocol v2
186 lines9.4 KiBRaw
1// GENERATED from README.md "Quick start" by test/e2e-customer.test.js (UPDATE_README_TYPETEST=1 rewrites it).
2// The README blocks as a TypeScript consumer writes them, plain strings for refs and paths: `npm run typecheck` compiles
3// it, under tsconfig.isolated.json too.
5// ---- setup ----
6const url = 'https://git.example.com/acme/site.git'; // an existing repository, empty or not
7const opts = { auth: { token: process.env['GIT_TOKEN'] } }; // add tracer: new Tracer({ exporter }) to export spans
8const author = { name: 'Release Bot', email: 'bot@example.com' }; // time defaults to now, tz to +0000
9const outDir = './site-checkout'; // checkoutDir writes here; it must be absent or empty
11// ---- first-commit ----
12import { pushTree } from '../../src/index.js';
14const first = await pushTree(url, {
15 ref: 'refs/heads/main',
16 files: {
17 'README.md': '# site\n',
18 'src/config.ts': 'export const VERSION = "1.2.3";\n',
19 'bin/build': { data: '#!/bin/sh\necho build\n', mode: '100755' },
20 },
21 author, message: 'Initial commit',
22}, opts);
23if (!first.ok) throw first.error;
24console.log(first.value.newCommit); // the commit id main now points at
26// ---- read ----
27import { readCommit, listTree, readFile } from '../../src/index.js';
29const head = await readCommit(url, { ref: 'main' }, opts);
30if (!head.ok) throw head.error;
31if ('empty' in head.value) throw new Error('main has no commits yet');
32console.log(head.value.oid, head.value.tree, head.value.parents, head.value.message);
34const listing = await listTree(url, { ref: 'main', path: 'src' }, opts);
35if (!listing.ok) throw listing.error;
36for (const e of listing.value.entries) console.log(e.mode, e.type, e.oid, e.name); // as git ls-tree prints them
38const file = await readFile(url, { ref: 'main', path: 'src/config.ts' }, opts);
39if (!file.ok) throw file.error;
40const config = await new Response(file.value.stream).text(); // read the stream to the end (or cancel it)
41console.log(file.value.size, config);
43// ---- edit ----
44import { editFile } from '../../src/index.js';
46const bump = await editFile(url, {
47 ref: 'refs/heads/main', path: 'src/config.ts',
48 find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"',
49 author, message: 'Bump version to 1.2.4',
50}, opts);
51if (!bump.ok) throw bump.error; // match_count when find is not there exactly once
52console.log(bump.value.newCommit, bump.value.noop); // noop: find === replace, nothing pushed
54// ---- commit-changes ----
55import { commitChanges } from '../../src/index.js';
57const change = await commitChanges(url, {
58 ref: 'refs/heads/main',
59 changes: [
60 { kind: 'create', path: 'docs/intro.md', content: '# Intro\n' }, // refuses a path that exists
61 { kind: 'write', path: 'README.md', content: '# site\n\nHello.\n' }, // creates or overwrites
62 { kind: 'edit', path: 'src/config.ts', find: '1.2.4', replace: '1.3.0' }, // exactly one match
63 { kind: 'delete', path: 'bin/build' }, // a file or a whole directory
64 { kind: 'rename', from: 'docs/intro.md', to: 'docs/index.md' },
65 ],
66 author, message: 'Docs; version 1.3.0',
67}, opts);
68if (!change.ok) throw change.error;
69console.log(change.value.outcome, change.value.oid); // 'commit', or 'noop' when the tree did not change
71// ---- branch-merge ----
72import { createBranch, mergeBranch } from '../../src/index.js';
74const feature = await createBranch(url, { ref: 'refs/heads/feature', from: 'main' }, opts);
75if (!feature.ok) throw feature.error; // cas_conflict when the branch already exists
77const work = await commitChanges(url, {
78 ref: 'refs/heads/feature',
79 changes: [{ kind: 'create', path: 'src/feature.ts', content: 'export const feature = true;\n' }],
80 author, message: 'Add feature flag',
81}, opts);
82if (!work.ok) throw work.error;
84const hotfix = await editFile(url, { // main moves on meanwhile
85 ref: 'refs/heads/main', path: 'README.md', find: 'Hello.', replace: 'Hello, world.', author, message: 'Fix greeting',
86}, opts);
87if (!hotfix.ok) throw hotfix.error;
89const merged = await mergeBranch(url, { ref: 'refs/heads/main', from: 'refs/heads/feature', author }, opts);
90if (!merged.ok) throw merged.error;
91console.log(merged.value.outcome, merged.value.oid); // 'merge': a commit with parents [main, feature]
93// ---- tag ----
94import { createTag } from '../../src/index.js';
96const release = await createTag(url, { name: 'v1.3.0', target: 'refs/heads/main' }, opts);
97if (!release.ok) throw release.error;
98const notes = await createTag(url, { name: 'v1.3.0-notes', target: release.value.commit, message: 'Release 1.3.0', tagger: author }, opts);
99if (!notes.ok) throw notes.error;
100console.log(notes.value.oid, notes.value.commit); // the tag object, and the commit it names
102// ---- rebase-pick-revert ----
103import { rebaseBranch, cherryPick, revertCommit } from '../../src/index.js';
105const topic = await createBranch(url, { ref: 'refs/heads/topic', from: 'refs/heads/main' }, opts);
106if (!topic.ok) throw topic.error;
107const onTopic = await commitChanges(url, { ref: 'refs/heads/topic', changes: [{ kind: 'create', path: 'src/topic.ts', content: 'export const topic = 1;\n' }], author, message: 'Add topic' }, opts);
108if (!onTopic.ok) throw onTopic.error;
109const onMain = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'create', path: 'CHANGELOG.md', content: '1.3.0\n' }], author, message: 'Changelog' }, opts);
110if (!onMain.ok) throw onMain.error;
112const rebased = await rebaseBranch(url, { ref: 'refs/heads/topic', onto: 'refs/heads/main', committer: author }, opts);
113if (!rebased.ok) throw rebased.error; // topic's commits replayed onto main's tip
115const picked = await cherryPick(url, { ref: 'refs/heads/main', commit: rebased.value.oid, committer: author }, opts);
116if (!picked.ok) throw picked.error; // outcome 'ok', or 'empty' when main already has the change (nothing written)
118const reverted = await revertCommit(url, { ref: 'refs/heads/main', commit: picked.value.oid, committer: author }, opts);
119if (!reverted.ok) throw reverted.error; // a 'Revert "Add topic"' commit on main
121// ---- history ----
122import { readLog } from '../../src/index.js';
124const log = await readLog(url, { ref: 'refs/heads/main', limit: 10 }, opts);
125if (!log.ok) throw log.error;
126for (const c of log.value.commits) console.log(c.oid.slice(0, 7), c.parents.length, c.message.split('\n')[0]);
128// ---- checkout ----
129import { checkoutTree } from '../../src/index.js';
130import { checkoutDir } from '../../src/checkout-node.js';
132const tree = await checkoutTree(url, { ref: 'v1.3.0' }, opts);
133if (!tree.ok) throw tree.error;
134for await (const f of tree.value.files) {
135 if (f.stream) console.log(f.path, f.mode, (await new Response(f.stream).arrayBuffer()).byteLength); // read each stream
138const written = await checkoutDir(url, { dir: outDir, ref: 'main' }, opts);
139if (!written.ok) throw written.error;
140console.log(written.value.written.files); // files written under outDir
142// ---- refs ----
143import { listRefs, deleteBranch, deleteTag } from '../../src/index.js';
145const refs = await listRefs(url, {}, opts); // branches and tags; { prefixes: ['refs/heads/'] } for branches only
146if (!refs.ok) throw refs.error;
147console.log(refs.value.head, refs.value.refs.map(r => r.name)); // 'refs/heads/main', [ 'refs/heads/feature', … ]
149const gone = await deleteBranch(url, { ref: 'refs/heads/feature', expected: work.value.oid }, opts);
150if (!gone.ok) throw gone.error; // cas_conflict when feature moved off that commit; not_found when it is gone
151const untagged = await deleteTag(url, { name: 'v1.3.0-notes' }, opts);
152if (!untagged.ok) throw untagged.error;
154// ---- errors ----
155import { assertNever } from '../../src/index.js';
157const stale = await editFile(url, {
158 ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "9.9.9"', replace: 'VERSION = "10.0.0"', author, message: 'Bump',
159}, opts);
160if (!stale.ok) {
161 const e = stale.error;
162 switch (e.code) {
163 case 'cas_conflict': // the ref moved between read and push (editFile already redid it once): read again, redo
164 console.warn('moved', e.expected, e.actual); break;
165 case 'match_count': // find matched e.matches times, not once: the file is not what you expected
166 console.warn('matches', e.matches); break;
167 case 'not_found': // e.miss.kind: 'ref' | 'path' | 'repository' | 'head_unborn' | 'commit' | …
168 console.warn('missing', e.miss.kind); break;
169 case 'auth': // 401/403: the credential is missing, wrong, or lacks write access
170 console.warn('auth'); break;
171 case 'limit_exceeded': // a limits.* bound (e.what, e.got, e.max): raise it with withLimits, or do less per call
172 console.warn('limit', e.what, e.got, e.max); break;
173 case 'ambiguous': // the push was sent and may have landed: read the ref back before doing anything else
174 console.warn('unknown outcome'); break;
175 case 'network': case 'timeout': case 'rate_limited': case 'upstream_5xx': case 'protocol': case 'pack_corrupt':
176 console.warn('transient: retry with backoff', e.code); break; // isRetryable(e) is true for exactly these
177 case 'merge_conflict': case 'not_fast_forward': case 'not_linear': case 'unrelated_histories':
178 console.warn('history needs a human', e.code); break;
179 case 'push_rejected': case 'push_partial': case 'remote_error': // a hook, branch protection, or the server said no
180 console.warn('refused', e.message); break;
181 case 'bad_request': case 'unsupported': case 'lfs_pointer': case 'http': case 'not_git': case 'aborted': case 'internal':
182 console.warn('fix the call or the setup', e.code, e.message); break;
183 default:
184 assertNever(e);
185 }
Diagnostics7 git calls · 31 ms
CallStatusSizeTime031 ms
discover200191 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=191
git.server.agent=git/github-9922ec520325-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=191
git.pkt.payload.max=36
ls-refs20012 KiB2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=11990
git.response.cache=UPDATING
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=152
git.pkt.data=151
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=11990
git.pkt.payload.max=122
git.ls_refs.count=151
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4347
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4347
git.pkt.payload.max=4247
git.sideband.band1.bytes=4247
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=10
git.pack.bytes=4247
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400
git.pack.full=10
Open pack map
fetchtree:0200919 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=919
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=919
git.pkt.payload.max=892
git.sideband.band1.bytes=892
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=892
git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76e
Open pack map
fetchtree:02005.6 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=5724
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=58fabb6768b3f737ee9cd8bac647bdc27405fb4d
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5724
git.pkt.payload.max=5697
git.sideband.band1.bytes=5697
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=5697
git.pack.trailer=be7e0453974a5fe832f9065a33bb7e3434c10e9b
Open pack map
fetchtree:0200746 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=17
git.response.bytes=746
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=1a4f84aea08d080a229290d401e77da8415108a0
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=746
git.pkt.payload.max=719
git.sideband.band1.bytes=719
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=719
git.pack.trailer=fd3904a205b94cd1bbf03c591c9acea7ca5dd5a7
Open pack map
fetch2003.2 KiB · hit17 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=3254
git.response.cache=HIT
git.response.duration_ms=17
git.fetch.wants=9324ad3470afdf4e3dc5aec4a075c5e2d144abf6
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=3254
git.pkt.payload.max=3227
git.sideband.band1.bytes=3227
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://github.com/ivarvong/ply
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e13c23cc5b1293
Request
fb5f91b1…
Protocol
v2 · sha1
Agent
git/github-9922ec520325-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format