Skip to content

docs: add demo GIF to README - #16

Merged
kova1max merged 1 commit into
mainfrom
fm/pullr-demo-gif
Nov 6, 2026
Merged

kova1max merged 1 commit into
mainfrom
fm/pullr-demo-gif

Conversation

@kova1max

@kova1max kova1max commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Intent

add pullr-demo.gif to README.md in pullr repo (Downloads)

The GIF is at ~/Downloads/pullr-demo.gif (159 KB), a demo recording of pullr.

What Changed

  • Added assets/pullr-demo.gif (159 KB), a terminal recording that shows pullr --dry-run ~/work previewing six repositories, then pullr ~/work updating, holding back, skipping and failing different repos.
  • Put the GIF in README.md right under the tagline, with descriptive alt text.

🤖 Generated with Claude Code

Risk Assessment

✅ Low: The change only adds a docs image and one README line. The committed GIF is byte-identical to ~/Downloads/pullr-demo.gif, and the image link uses a valid relative path with descriptive alt text.

Testing

This change only adds a docs image, so there is no runtime CLI behaviour to exercise. I checked that the committed GIF is byte-identical to the source file with cmp. I rendered README.md to GFM HTML with marked and screenshotted it in headless Chrome: the 1200x500 GIF shows right below the tagline. I also decoded the 344 GIF frames in Chrome and compared key frames with the alt text, and they match: six repos in the dry run, then api and web updated, docs held back, scratch skipped and infra diverged. The worktree is still clean.

  • Live validation: ⚠️ no-surface - 0 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Reader opens README and sees the pullr demo GIF rendered under the tagline ⏸️ untested no This is a docs-only change with no runtime product surface. I checked it with a local GFM render and a headless Chrome screenshot: the GIF loads and displays correctly.
Committed GIF is the user's ~/Downloads/pullr-demo.gif ⏸️ untested no Docs and asset only, so there is no live product to drive. The byte comparison passed.
Alt text accurately describes the recording ⏸️ untested no Docs only. Frames I decoded in headless Chrome match the alt text: six repos in the dry run, api and web updated, docs held back, scratch skipped, infra diverged.

Rendered README with embedded demo GIF
GIF key frames (dry-run, real run, final)

Evidence: Rendered README HTML
<html><head><meta charset="utf-8"><style>body{max-width:980px;margin:24px auto;font-family:-apple-system,Helvetica,Arial;line-height:1.5;padding:0 32px}img{max-width:100%}code{background:#eff1f3;padding:2px 4px;border-radius:4px}</style></head><body>
<h1>pullr</h1>
<p><a href="https://github.com/kova1max/pullr/actions/workflows/ci.yml"><img src="https://github.com/kova1max/pullr/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/@kova1/pullr"><img src="https://img.shields.io/npm/v/%40kova1%2Fpullr?logo=npm&label=npm" alt="npm"></a>
<a href="https://github.com/kova1max/homebrew-tap"><img src="https://img.shields.io/github/v/release/kova1max/pullr?logo=homebrew&label=homebrew" alt="Homebrew"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/kova1max/pullr" alt="License: MIT"></a></p>
<p>Safe, fast-forward pull every git repository under a directory.</p>
<p><img src="pullr-demo.gif" alt="Terminal recording of pullr --dry-run ~/work previewing six repositories, then pullr ~/work updating api and web, holding back docs on conflicting local changes, skipping scratch with no upstream, and failing infra which diverged from upstream"></p>
<p>Built for workspaces made of many independent repositories, where keeping
everything current means <code>cd</code>-ing into each one.</p>
<pre><code class="language-console">$ pullr ~/work
+ api (main, 3 new commits)
+ web (main, 1 new commit, local changes reapplied)
~ docs (main, 2 commits held back because local changes conflict with them)
- scratch (main has no upstream)
x infra (main)
    diverged from upstream (behind 2, ahead 1): cannot fast-forward

Repos: 5  updated: 2  up to date: 0  dirty: 1  skipped: 1  failed: 1
Dirty: docs
Failed: infra
</code></pre>
<h2>Install</h2>
<pre><code class="language-sh"># Homebrew
brew install kova1max/tap/pullr

# npm
npm install -g @kova1/pullr
</code></pre>
<p>To try it without installing anything:</p>
<pre><code class="language-sh">npx @kova1/pullr --dry-run ~/work
</code></pre>
<p>Every release is also mirrored to
<a href="https://github.com/kova1max/pullr/pkgs/npm/pullr">GitHub Packages</a> as
<code>@kova1max/pullr</code> (GitHub requires the repo owner as scope). Installing from
there needs a GitHub token, so the npm registry above is the easier choice.</p>
<h2>What it will never do</h2>
<p>pullr is built to be safe to run across a whole workspace without looking
first. It will never:</p>
<ul>
<li><strong>Create a merge commit.</strong> Pulls are fast-forward only.</li>
<li><strong>Touch a branch that has diverged</strong> from its upstream. It is reported as
failed and left exactly as it was. Rebasing it is opt-in with <code>--rebase</code>,
and a rebase that hits a conflict is aborted, leaving the repository as it
was.</li>
<li><strong>Leave your changes half-merged, or lose them.</strong> When local edits or
untracked files are in the way of an update, pullr stashes them, updates,
and re-applies them on top. If they conflict with the incoming commits, it
puts the repository back exactly as it was - same commit, same files, same
staged and unstaged changes, no stash left behind - and reports it as
dirty. Edits that don&#39;t touch incoming files are never stashed at all.
<code>--no-autostash</code> skips the stash and just reports the repository as dirty.</li>
<li><strong>Touch a repository on a detached <code>HEAD</code></strong>, or a branch with no upstream.
Both are skipped.</li>
<li><strong>Enter a nested repository.</strong> Repositories inside another repository are
left to their parent.</li>
<li><strong>Move a submodule off its branch.</strong> With <code>--submodules</code>, a submodule is
only ever fast-forwarded on the branch it is on. (If you set git&#39;s
<code>submodule.recurse</code>, pullr does what <code>git pull</code> does with it: checks
submodules out at the recorded commit.)</li>
<li><strong>Follow symlinked directories.</strong></li>
</ul>
<h2>Usage</h2>
<pre><code>pullr [options] [DIR]
</code></pre>
<p>Short options can be combined: <code>-rs</code> is <code>-r -s</code>, and <code>-j8</code> or <code>-rj 8</code> set
the number of jobs.</p>
<table>
<thead>
<tr>
<th align="left">Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</th>
<th align="left">Default</th>
<th align="left">Meaning</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>DIR</code></td>
<td align="left">current&nbsp;directory</td>
<td align="left">Where to look for repositories</td>
</tr>
<tr>
<td align="left"><code>-j</code>, <code>--jobs N</code></td>
<td align="left"><code>8</code></td>
<td align="left">Work on up to <code>N</code> repositories in parallel. Output is buffered per repository and printed in discovery order, so it reads the same as a sequential run. With <code>N &gt; 1</code> git never prompts for credentials; use <code>--jobs 1</code> for repositories that need an interactive login.</td>
</tr>
<tr>
<td align="left"><code>--max-depth N</code></td>
<td align="left"><code>2</code></td>
<td align="left">How many directory levels below <code>DIR</code> to search. <code>0</code> = only <code>DIR</code> itself, <code>1</code> = <code>DIR</code> and its direct children, ...</td>
</tr>
<tr>
<td align="left"><code>-n</code>, <code>--dry-run</code></td>
<td align="left"></td>
<td align="left">Show what a run would do without pulling, see below</td>
</tr>
<tr>
<td align="left"><code>-r</code>, <code>--rebase</code></td>
<td align="left">off</td>
<td align="left">Rebase local commits onto the upstream instead of refusing a diverged branch (<code>git pull --rebase</code>). A rebase that hits a conflict is aborted and the repository is left as it was.</td>
</tr>
<tr>
<td align="left"><code>--no-autostash</code></td>
<td align="left"></td>
<td align="left">Don&#39;t stash local changes that are in the way of an update; report the repository as dirty instead. Autostash is on by default, see &quot;What it will never do&quot;.</td>
</tr>
<tr>
<td align="left"><code>-s</code>, <code>--submodules</code></td>
<td align="left">off</td>
<td align="left">Also fast-forward each submodule that is checked out on a branch, see below</td>
</tr>
<tr>
<td align="left"><code>--no-color</code></td>
<td align="left"></td>
<td align="left">Disable colored output. Also disabled when the <a href="https://no-color.org"><code>NO_COLOR</code></a> environment variable is set, or when output is not a terminal.</td>
</tr>
<tr>
<td align="left"><code>-V</code>, <code>--version</code></td>
<td align="left"></td>
<td align="left">Print the version</td>
</tr>
<tr>
<td align="left"><code>-h</code>, <code>--help</code></td>
<td align="left"></td>
<td align="left">Show help</td>
</tr>
</tbody></table>
<h3>Output</h3>
<p>Each repository gets one line: <code>+</code> updated, <code>=</code> already up to date, <code>~</code>
dirty (local changes conflict with the update, which is held back), <code>-</code>
skipped, <code>x</code> failed (with the reason indented below it). Exits <code>1</code> if any
pull failed, <code>2</code> on invalid arguments, <code>0</code> otherwise; a dirty repository is
not a failure.</p>
<h3>Dry run</h3>
<p><code>pullr --dry-run</code> shows what a run would do, without pulling:</p>
<pre><code class="language-console">$ pullr --dry-run ~/work
Dry run: nothing will be pulled.
+ api (main, 3 new commits)
= web (main)
x infra (main)
    diverged from upstream (behind 2, ahead 1): cannot fast-forward
- scratch (main has no upstream)

Repos: 4  would update: 1  up to date: 1  dirty: 0  skipped: 1  would fail: 1
Failed: infra
</code></pre>
<p>It runs <code>git fetch</code> in each repository first, so the answer reflects the
remote as it is now, then prints the same lines a real run would. An update
that would need to stash local changes shows as <code>+ ... , local changes to autostash</code>, and with <code>--rebase</code> a diverged repository shows as
<code>+ ... , 2 to rebase</code> instead of <code>x</code>; whether re-applying or rebasing would
conflict is only known by running it. Fetching
only updates remote-tracking refs: the working tree and current branch are
never modified. Exit codes match a real run.</p>
<h3>Submodules</h3>
<p>By default pullr updates a repository the way <code>git pull</code> does: submodules stay
where they are, unless you set git&#39;s <code>submodule.recurse</code>, in which case they
are checked out at the commits the parent now records, as <code>git pull</code> would.</p>
<p><code>--submodules</code> is for working inside submodules. Each submodule that is
checked out on a branch is treated as a repository of its own - fetched,
fast-forwarded with the same rules, and listed under its parent:</p>
<pre><code class="language-console">$ pullr --submodules ~/work
+ app (main, 2 new commits)
  + app/lib/core (main, 5 new commits)
  - app/vendor/sdk (detached HEAD)
</code></pre>
<p>Submodules on a detached HEAD (git&#39;s default after <code>git submodule update</code>) are
skipped, and uninitialized ones are left out.</p>
<h2>How it compares</h2>
<table>
<thead>
<tr>
<th align="left"></th>
<th align="left">pullr</th>
<th align="left"><a href="https://github.com/nosarthur/gita">gita</a></th>
<th align="left"><a href="https://github.com/earwig/git-repo-updater">gitup</a></th>
<th align="left"><a href="https://myrepos.branchable.com">myrepos</a> (<code>mr</code>)</th>
<th align="left"><a href="https://github.com/alajmo/mani">mani</a></th>
</tr>
</thead>
<tbody><tr>
<td align="left">Needs</td>
<td align="left">bash and git</td>
<td align="left">Python&nbsp;3.8+</td>
<td align="left">Python&nbsp;3.10+</td>
<td align="left">Perl</td>
<td align="left">Go binary</td>
</tr>
<tr>
<td align="left">Finds repos</td>
<td align="left">scans a directory</td>
<td align="left">register first (<code>gita add</code>)</td>
<td align="left">scans a directory</td>
<td align="left">register first (<code>~/.mrconfig</code>)</td>
<td align="left">register first (<code>mani.yaml</code>)</td>
</tr>
<tr>
<td align="left">Pulls in parallel</td>
<td align="left">8 at a time by default</td>
<td align="left">all at once, no limit</td>
<td align="left">no</td>
<td align="left">opt-in</td>
<td align="left">opt-in</td>
</tr>
<tr>
<td align="left">Update</td>
<td align="left">fetch + fast&#8209;forward</td>
<td align="left"><code>git pull</code></td>
<td align="left">fetch + fast&#8209;forward</td>
<td align="left"><code>git pull</code></td>
<td align="left">no built-in pull</td>
</tr>
<tr>
<td align="left">Merge commits</td>
<td align="left">never</td>
<td align="left">depends on your git config</td>
<td align="left">never</td>
<td align="left">depends on your git config</td>
<td align="left">depends on your command</td>
</tr>
<tr>
<td align="left">Local changes in the way</td>
<td align="left">stashed and reapplied; rolled back on conflict</td>
<td align="left">git&#39;s error</td>
<td align="left">skipped</td>
<td align="left">git&#39;s error</td>
<td align="left">-</td>
</tr>
<tr>
<td align="left">Dry run</td>
<td align="left">yes</td>
<td align="left">no</td>
<td align="left">no</td>
<td align="left">no</td>
<td align="left">prints commands</td>
</tr>
</tbody></table>
<p><strong>Why &quot;8 at a time&quot; and not &quot;all at once&quot;.</strong> Many self-hosted git servers
limit how many SSH connections can be opening at the same time; OpenSSH&#39;s
default (<code>MaxStartups 10:30:100</code>) starts refusing them past 10. Fetching
every repository at once then fails for reasons that have nothing to do with
your repositories. On a self-hosted GitLab with 61 repositories, 16 parallel
fetches produced 6-9 of those spurious failures and 32 produced 10-14, while
8 produced none. GitHub itself handled 64 at once without errors, so raise
<code>-j</code> freely there.</p>
<h2>License</h2>
<p><a href="LICENSE">MIT</a></p>

</body></html>
- Outcome: ⚠️ 1 warning across 1 run (1m29s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 1 warning
  • ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 3 scenarios were driven live against the product); Reader opens README and sees the pullr demo GIF rendered under the tagline: This is a docs-only change with no runtime product surface. I checked it with a local GFM render and a headless Chrome screenshot: the GIF loads and displays correctly.; Committed GIF is the user's ~/Downloads/pullr-demo.gif: Docs and asset only, so there is no live product to drive. The byte comparison passed.; Alt text accurately describes the recording: Docs only. Frames I decoded in headless Chrome match the alt text: six repos in the dry run, api and web updated, docs held back, scratch skipped, infra diverged.
  • Live validation: ⚠️ no-surface - 0 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Reader opens README and sees the pullr demo GIF rendered under the tagline ⏸️ untested no This is a docs-only change with no runtime product surface. I checked it with a local GFM render and a headless Chrome screenshot: the GIF loads and displays correctly.
Committed GIF is the user's ~/Downloads/pullr-demo.gif ⏸️ untested no Docs and asset only, so there is no live product to drive. The byte comparison passed.
Alt text accurately describes the recording ⏸️ untested no Docs only. Frames I decoded in headless Chrome match the alt text: six repos in the dry run, api and web updated, docs held back, scratch skipped, infra diverged.
  • cmp assets/pullr-demo.gif ~/Downloads/pullr-demo.gif (identical)
  • npx marked --gfm render of README.md + headless Chrome screenshot
  • Headless Chrome ImageDecoder extraction of GIF frames 154/206/343 to verify alt text accuracy
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@kova1max
kova1max merged commit f0c07bd into main Nov 6, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant