GitLabgitlab-org

cli

main
ply6 git calls34 ms97 KiB4 cachedprotocol v2
102 lines3.8 KiBRaw

Demo recordings

Terminal demos in this repository are generated from VHS tape files. A tape is a plain-text script that drives a virtual terminal and produces a deterministic GIF. When you store tapes in the repo, anyone with VHS installed can review the recordings, compare changes between versions, and reproduce them locally.

Install VHS

shell
# macOS
brew install vhs

# Other platforms: https://github.com/charmbracelet/vhs#installation

VHS also requires ttyd and ffmpeg. Homebrew installs both as dependencies.

Run an existing tape

Run tapes from this directory:

shell
cd docs/demos
vhs getting-started.tape

Each tape stages its own working directory in a hidden setup block, so glab picks up a project from a git remote no matter where you launch VHS from. Output paths in tape files are relative to this directory.

Shared styling

All tapes begin with Source base.tape, which pulls in the canonical terminal settings: dimensions, theme, typography, frame, and window bar. To change the look across every demo at once, edit base.tape. In a per-tape file, include only:

  • The Source base.tape line.
  • An Output directive for that tape's GIF.
  • A Hide ... Show block that stages the working directory and prompt.
  • The script itself.

base.tape is a partial. It contains only Set directives. Do not run it directly with vhs.

Authentication

Tapes invoke glab against the live GitLab API, so you need to pass a valid token through the environment when you run vhs:

shell
GITLAB_TOKEN="<your-personal-access-token>" vhs getting-started.tape

glab reads GITLAB_TOKEN before the keyring and config file, and VHS inherits its parent's environment, so the token reaches every command in the tape. To target a non-gitlab.com instance, set GITLAB_HOST the same way.

Notes on token usage:

  • The token needs only the read_api scope. When a tape clones over SSH, git uses your SSH key, and the token isn't consulted for that step.
  • Don't bake tokens into tape files. Always pass tokens through the environment at recording time.
  • When your interactive shell wraps glab in an alias (for example, alias glab='op plugin run -- glab'), the bash session that VHS spawns might not inherit the alias, depending on your .bashrc. The bundled tapes defensively run unalias glab in their hidden setup block so they always exercise the binary on PATH. Do the same in new tapes.

Add a new tape

getting-started.tape is the reference example. Use it as the starting point for new tapes.

  1. Create a new docs/demos/<name>.tape file.
  2. Copy the contents of getting-started.tape to your new file. Keep the Source, Output, and Hide...Show blocks. You'll edit them in the next two steps.
  3. Update the header comment and the Output path for your demo.
  4. Update the Output path to point to your new GIF.
  5. Replace the script section (everything after the Show directive) with the commands you want to record.
  6. Run vhs <name>.tape to generate the GIF.
  7. Commit the .tape file and the generated GIF together.

Guidelines for tape content

When you write the script, follow these conventions:

  • Prefer flags that bound output, such as --per-page and --limit, instead of relying on the default config. The recording should look the same on any machine.
  • To time a long-running command, use Wait+Screen /regex/ instead of Sleep so the recording adapts to network latency.

Current tapes

TapeOutputUsed in
base.tape(partial, sourced by other tapes)All demos
getting-started.tape../source/img/getting-started.gifREADME.md, docs/source/_index.md
1# Demo recordings
3Terminal demos in this repository are generated from [VHS](https://github.com/charmbracelet/vhs)
4tape files. A tape is a plain-text script that drives a virtual terminal and
5produces a deterministic GIF. When you store tapes in the repo, anyone with VHS installed can review the recordings, compare changes between versions, and reproduce them locally.
7## Install VHS
9```shell
10# macOS
11brew install vhs
13# Other platforms: https://github.com/charmbracelet/vhs#installation
14```
16VHS also requires `ttyd` and `ffmpeg`. Homebrew installs both as dependencies.
18## Run an existing tape
20Run tapes from this directory:
22```shell
23cd docs/demos
24vhs getting-started.tape
25```
27Each tape stages its own working directory in a hidden setup block, so `glab`
28picks up a project from a `git` remote no matter where you launch VHS from.
29Output paths in tape files are relative to this directory.
31## Shared styling
33All tapes begin with `Source base.tape`, which pulls in the canonical terminal
34settings: dimensions, theme, typography, frame, and window bar. To change the
35look across every demo at once, edit `base.tape`. In a per-tape file, include
36only:
38- The `Source base.tape` line.
39- An `Output` directive for that tape's GIF.
40- A `Hide` ... `Show` block that stages the working directory and prompt.
41- The script itself.
43`base.tape` is a partial. It contains only `Set` directives. Do not run it
44directly with `vhs`.
46## Authentication
48Tapes invoke `glab` against the live GitLab API, so you need to pass a valid
49token through the environment when you run `vhs`:
51```shell
52GITLAB_TOKEN="<your-personal-access-token>" vhs getting-started.tape
53```
55`glab` reads `GITLAB_TOKEN` before the keyring and config file, and VHS
56inherits its parent's environment, so the token reaches every command in the
57tape. To target a non-`gitlab.com` instance, set `GITLAB_HOST` the same way.
59Notes on token usage:
61- The token needs only the `read_api` scope. When a tape clones over SSH,
62 `git` uses your SSH key, and the token isn't consulted for that step.
63- Don't bake tokens into tape files. Always pass tokens through the
64 environment at recording time.
65- When your interactive shell wraps `glab` in an alias (for example,
66 `alias glab='op plugin run -- glab'`), the bash session that VHS spawns
67 might not inherit the alias, depending on your `.bashrc`. The bundled
68 tapes defensively run `unalias glab` in their hidden setup block so they
69 always exercise the binary on `PATH`. Do the same in new tapes.
71## Add a new tape
73`getting-started.tape` is the reference example. Use it as the starting
74point for new tapes.
761. Create a new `docs/demos/<name>.tape` file.
771. Copy the contents of `getting-started.tape` to your new file. Keep the
78 `Source`, `Output`, and `Hide`...`Show` blocks. You'll edit them in
79 the next two steps.
801. Update the header comment and the `Output` path for your demo.
811. Update the `Output` path to point to your new GIF.
821. Replace the script section (everything after the `Show` directive)
83 with the commands you want to record.
841. Run `vhs <name>.tape` to generate the GIF.
851. Commit the `.tape` file and the generated GIF together.
87### Guidelines for tape content
89When you write the script, follow these conventions:
91- Prefer flags that bound output, such as `--per-page` and `--limit`,
92 instead of relying on the default config. The recording should look
93 the same on any machine.
94- To time a long-running command, use `Wait+Screen /regex/` instead of
95 `Sleep` so the recording adapts to network latency.
97## Current tapes
99| Tape | Output | Used in |
100|------------------------|-------------------------------------|---------|
101| `base.tape` | _(partial, sourced by other tapes)_ | All demos |
102| `getting-started.tape` | `../source/img/getting-started.gif` | `README.md`, `docs/source/_index.md` |
Diagnostics6 git calls · 34 ms
CallStatusSizeTime034 ms
discover200185 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=185
git.server.agent=git/2.56.g1891de4-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=185
git.pkt.payload.max=35
ls-refs20058 KiB1 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=1
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=1
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
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=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
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=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0200181 B · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=22
git.response.bytes=181
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.filter=tree:0
git.fetch.wants=a537298b741e34ac5320fbaf9c524fb8fe78efa3
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=181
git.pkt.payload.max=154
git.sideband.band1.bytes=154
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=154
git.pack.trailer=0eb5a6ec5901fc5c555d576ac2f5a3837df6ff8c
Open pack map
fetch2001.9 KiB · hit23 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1898
git.response.cache=HIT
git.response.duration_ms=23
git.fetch.wants=58e5468a6bef68f49bc9a9a809e14fdfcf802651
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=1898
git.pkt.payload.max=1871
git.sideband.band1.bytes=1871
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://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e20e616cbc7f3b
Request
630a8f0a…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format