pulli 0.2.1__tar.gz → 0.2.5__tar.gz

{pulli-0.2.1 → pulli-0.2.5}/.gitignore

@@ -16,5 +16,11 @@ env/
 dist/
 build/
 
+# Local secrets / env
+.env
+.env.local
+.env.*
+!.env.example
+
 # OS
 .DS_Store

{pulli-0.2.1 → pulli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pulli
-Version: 0.2.1
+Version: 0.2.5
 Summary: Walk a directory tree, show git repos with status, and fast-forward the ones that are behind upstream.
 Author: Stefan Waldherr
 License-Expression: MIT
@@ -22,16 +22,34 @@ fast-forward the ones that are behind upstream.
 
 ## Install
 
+### Permanently (on your PATH)
+
 ```bash
-uv tool install git+https://github.com/devskale/pulli
+uv tool install pulli
 # or
-pipx install git+https://github.com/devskale/pulli
+pipx install pulli
 ```
 
-Both put `pulli` on your PATH (`~/.local/bin/pulli`). To install a local
-checkout instead (development):
+Both put `pulli` on your PATH (`~/.local/bin/pulli`). After that just run
+`pulli`.
+
+### Once, without installing (`uvx`)
 
 ```bash
+uvx pulli
+uvx pulli ~/code
+```
+
+`uvx` fetches `pulli` from PyPI into a temporary cache and runs it
+immediately — no permanent install, no PATH entry. Great for a one-off run
+or to try it out. `uv run --from pulli pulli` does the same thing inside a
+`uv run` context.
+
+### From Git / a dev checkout
+
+```bash
+uv tool install git+https://github.com/devskale/pulli
+# or, for a local checkout (development)
 cd ~/code/pulli
 uv tool install --force .
 ```
@@ -57,12 +75,20 @@ connectors).
 | flag | effect |
 | --- | --- |
 | `--tree` | show the full directory tree instead of the flat repo list |
+| `--behind` | only the repos that need a pull |
+| `--attention` | only dirty / diverged / behind / broken repos — what needs you first |
+| `--no-summary` | omit the one-line summary under the list |
 | `--no-fetch` | don't fetch remotes before showing status |
 | `--no-symlinks` | don't follow symlinks (default: follow, marked) |
 | `--max-depth N` | limit recursion (default: 50) |
-| `--no-color` | disable ANSI colours (also implied off a TTY) |
+| `--no-color` | disable ANSI colours (also implied off a TTY, by `NO_COLOR`, or `TERM=dumb`) |
 | `--json` | one JSON object per line, for scripts |
 
+`pulli --examples` prints a cheat sheet of common invocations.
+
+The list ends with a one-line summary (`56 repos · 16 behind · 1 diverged …`),
+so a scan answers "how are my repos doing?" without counting lines.
+
 Fetches run in parallel by default, so ahead/behind is current, and each is
 bounded by a short timeout — if you're offline (on a train) unreachable
 remotes are reported as `offline` and the tree still renders.
@@ -73,6 +99,20 @@ frozen. The spinner only appears on a real terminal; when output is piped
 or captured (`pulli | less`, CI, scripts) it is a no-op and the output stays
 byte-clean. `--no-color` disables the spinner's colouring too.
 
+### `update`
+
+Checks PyPI and upgrades pulli itself — the installer that owns the binary
+(`uv tool` or `pipx`) decides the upgrade command.
+
+```bash
+pulli update            # upgrade to the latest PyPI release
+pulli update --check   # show what would be updated, change nothing
+```
+
+`pulli --version` also reports when a newer release exists. The check hits
+PyPI at most once a day (cached in the platform cache dir), never touches
+the output of normal runs, and is silent when offline.
+
 ### `pull`
 
 | flag | effect |
@@ -92,9 +132,10 @@ corrupt work to make progress.
 | repo state | action |
 | --- | --- |
 | behind upstream, clean | `git pull --ff-only` |
+| behind upstream, **untracked files only** | `git pull --ff-only` — untracked files cannot conflict with a fast-forward, so they are kept and the repo is pulled (marked `untracked N` instead of `dirty N`) |
 | up to date | nothing (silent) |
 | ahead only | nothing — local commits need a *push*, not a pull |
-| uncommitted changes | skipped, reported |
+| uncommitted changes (tracked) | skipped, with the way out: *commit or stash, then pulli pull again* |
 | diverged (ahead **and** behind) | skipped — a fast-forward is impossible; merge or rebase is your call |
 | merge / rebase / bisect in progress | skipped, reported — never touched |
 | no upstream (detached HEAD, no remote) | nothing to pull |
@@ -126,7 +167,7 @@ Would pull 1 repo(s).
 ### Flat list (default)
 
 ```
-clones/pi  earendil-works/pi  main  ↓0 ↑0  ● clean
+clones/pi  earendil-works/pi  main  ↓0 ↑0  ●
 clones/gogcli  openclaw/gogcli  main  ↓0 ↑0  ◐ dirty 5
 kontext.one  devskale/kontext.one  main  ↓0 ↑0  ◐ dirty 5
 ```
@@ -139,13 +180,13 @@ sorted by path, so a run is reproducible.
 ```
 ~/code
 ├── clones/
-│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ● clean
-│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ● clean
+│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ●
+│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ●
 │   └── gogcli   openclaw/gogcli       main    ↓0 ↑0  ◐ dirty 5
 ├── handoffs -> code/skaleshare/handoffs (alias)
 ├── kontext.one  devskale/kontext.one  main    ↓0 ↑0  ◐ dirty 5
-│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ● clean
-│   └── python-utils (submodule)                   ↓0 ↑0  ● clean
+│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ●
+│   └── python-utils (submodule)                   ↓0 ↑0  ●
 └── backups/
     └── model-proxy.git/  (bare repo — nothing to pull)
 ```
@@ -155,13 +196,13 @@ sorted by path, so a run is reproducible.
 ```
 ~/code
 ├── clones/
-│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ● clean
-│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ● clean
+│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ●
+│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ●
 │   └── gogcli   openclaw/gogcli       main    ↓0 ↑0  ◐ dirty 5
 ├── handoffs -> code/skaleshare/handoffs (alias)
 ├── kontext.one  devskale/kontext.one  main    ↓0 ↑0  ◐ dirty 5
-│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ● clean
-│   └── python-utils (submodule)                   ↓0 ↑0  ● clean
+│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ●
+│   └── python-utils (submodule)                   ↓0 ↑0  ●
 └── backups/
     └── model-proxy.git/  (bare repo — nothing to pull)
 ```
@@ -169,8 +210,10 @@ sorted by path, so a run is reproducible.
 - **`↓N ↑M`** — commits behind / ahead of upstream; `·  ·` means there is
   no upstream to compare against (a fresh `git init`, a detached HEAD, a
   remote-less clone), which is not the same as "in sync"
-- **`●` clean / `◐` dirty N / `✗` error** — `◐ offline` means the fetch
-  failed, so the numbers may be stale
+- **`●` clean (default) / `◐` dirty N / `✗` error** — `◐ offline` means the fetch
+  failed, so the numbers may be stale. Untracked-only content renders as
+  `◐ untracked N` (dim), not dirty: git itself does not consider untracked
+  content dirty, and a pull cannot conflict with it
 - **symlinks** are followed by default and marked; one whose target is also
   reachable under its real name is shown as an `(alias)` and is never a
   second pull target. `--no-symlinks` skips them

{pulli-0.2.1 → pulli-0.2.5}/README.md

@@ -5,16 +5,34 @@ fast-forward the ones that are behind upstream.
 
 ## Install
 
+### Permanently (on your PATH)
+
 ```bash
-uv tool install git+https://github.com/devskale/pulli
+uv tool install pulli
 # or
-pipx install git+https://github.com/devskale/pulli
+pipx install pulli
 ```
 
-Both put `pulli` on your PATH (`~/.local/bin/pulli`). To install a local
-checkout instead (development):
+Both put `pulli` on your PATH (`~/.local/bin/pulli`). After that just run
+`pulli`.
+
+### Once, without installing (`uvx`)
 
 ```bash
+uvx pulli
+uvx pulli ~/code
+```
+
+`uvx` fetches `pulli` from PyPI into a temporary cache and runs it
+immediately — no permanent install, no PATH entry. Great for a one-off run
+or to try it out. `uv run --from pulli pulli` does the same thing inside a
+`uv run` context.
+
+### From Git / a dev checkout
+
+```bash
+uv tool install git+https://github.com/devskale/pulli
+# or, for a local checkout (development)
 cd ~/code/pulli
 uv tool install --force .
 ```
@@ -40,12 +58,20 @@ connectors).
 | flag | effect |
 | --- | --- |
 | `--tree` | show the full directory tree instead of the flat repo list |
+| `--behind` | only the repos that need a pull |
+| `--attention` | only dirty / diverged / behind / broken repos — what needs you first |
+| `--no-summary` | omit the one-line summary under the list |
 | `--no-fetch` | don't fetch remotes before showing status |
 | `--no-symlinks` | don't follow symlinks (default: follow, marked) |
 | `--max-depth N` | limit recursion (default: 50) |
-| `--no-color` | disable ANSI colours (also implied off a TTY) |
+| `--no-color` | disable ANSI colours (also implied off a TTY, by `NO_COLOR`, or `TERM=dumb`) |
 | `--json` | one JSON object per line, for scripts |
 
+`pulli --examples` prints a cheat sheet of common invocations.
+
+The list ends with a one-line summary (`56 repos · 16 behind · 1 diverged …`),
+so a scan answers "how are my repos doing?" without counting lines.
+
 Fetches run in parallel by default, so ahead/behind is current, and each is
 bounded by a short timeout — if you're offline (on a train) unreachable
 remotes are reported as `offline` and the tree still renders.
@@ -56,6 +82,20 @@ frozen. The spinner only appears on a real terminal; when output is piped
 or captured (`pulli | less`, CI, scripts) it is a no-op and the output stays
 byte-clean. `--no-color` disables the spinner's colouring too.
 
+### `update`
+
+Checks PyPI and upgrades pulli itself — the installer that owns the binary
+(`uv tool` or `pipx`) decides the upgrade command.
+
+```bash
+pulli update            # upgrade to the latest PyPI release
+pulli update --check   # show what would be updated, change nothing
+```
+
+`pulli --version` also reports when a newer release exists. The check hits
+PyPI at most once a day (cached in the platform cache dir), never touches
+the output of normal runs, and is silent when offline.
+
 ### `pull`
 
 | flag | effect |
@@ -75,9 +115,10 @@ corrupt work to make progress.
 | repo state | action |
 | --- | --- |
 | behind upstream, clean | `git pull --ff-only` |
+| behind upstream, **untracked files only** | `git pull --ff-only` — untracked files cannot conflict with a fast-forward, so they are kept and the repo is pulled (marked `untracked N` instead of `dirty N`) |
 | up to date | nothing (silent) |
 | ahead only | nothing — local commits need a *push*, not a pull |
-| uncommitted changes | skipped, reported |
+| uncommitted changes (tracked) | skipped, with the way out: *commit or stash, then pulli pull again* |
 | diverged (ahead **and** behind) | skipped — a fast-forward is impossible; merge or rebase is your call |
 | merge / rebase / bisect in progress | skipped, reported — never touched |
 | no upstream (detached HEAD, no remote) | nothing to pull |
@@ -109,7 +150,7 @@ Would pull 1 repo(s).
 ### Flat list (default)
 
 ```
-clones/pi  earendil-works/pi  main  ↓0 ↑0  ● clean
+clones/pi  earendil-works/pi  main  ↓0 ↑0  ●
 clones/gogcli  openclaw/gogcli  main  ↓0 ↑0  ◐ dirty 5
 kontext.one  devskale/kontext.one  main  ↓0 ↑0  ◐ dirty 5
 ```
@@ -122,13 +163,13 @@ sorted by path, so a run is reproducible.
 ```
 ~/code
 ├── clones/
-│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ● clean
-│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ● clean
+│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ●
+│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ●
 │   └── gogcli   openclaw/gogcli       main    ↓0 ↑0  ◐ dirty 5
 ├── handoffs -> code/skaleshare/handoffs (alias)
 ├── kontext.one  devskale/kontext.one  main    ↓0 ↑0  ◐ dirty 5
-│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ● clean
-│   └── python-utils (submodule)                   ↓0 ↑0  ● clean
+│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ●
+│   └── python-utils (submodule)                   ↓0 ↑0  ●
 └── backups/
     └── model-proxy.git/  (bare repo — nothing to pull)
 ```
@@ -138,13 +179,13 @@ sorted by path, so a run is reproducible.
 ```
 ~/code
 ├── clones/
-│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ● clean
-│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ● clean
+│   ├── herdr    ogulcancelik/herdr    master  ↓0 ↑0  ●
+│   ├── pi       earendil-works/pi     main    ↓33 ↑0 ●
 │   └── gogcli   openclaw/gogcli       main    ↓0 ↑0  ◐ dirty 5
 ├── handoffs -> code/skaleshare/handoffs (alias)
 ├── kontext.one  devskale/kontext.one  main    ↓0 ↑0  ◐ dirty 5
-│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ● clean
-│   └── python-utils (submodule)                   ↓0 ↑0  ● clean
+│   ├── klark0     devskale/klark0      dev     ↓0 ↑0  ●
+│   └── python-utils (submodule)                   ↓0 ↑0  ●
 └── backups/
     └── model-proxy.git/  (bare repo — nothing to pull)
 ```
@@ -152,8 +193,10 @@ sorted by path, so a run is reproducible.
 - **`↓N ↑M`** — commits behind / ahead of upstream; `·  ·` means there is
   no upstream to compare against (a fresh `git init`, a detached HEAD, a
   remote-less clone), which is not the same as "in sync"
-- **`●` clean / `◐` dirty N / `✗` error** — `◐ offline` means the fetch
-  failed, so the numbers may be stale
+- **`●` clean (default) / `◐` dirty N / `✗` error** — `◐ offline` means the fetch
+  failed, so the numbers may be stale. Untracked-only content renders as
+  `◐ untracked N` (dim), not dirty: git itself does not consider untracked
+  content dirty, and a pull cannot conflict with it
 - **symlinks** are followed by default and marked; one whose target is also
   reachable under its real name is shown as an `(alias)` and is never a
   second pull target. `--no-symlinks` skips them

pulli-0.2.5/scripts/release.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Local release builder — zero GitHub Actions minutes.
+# Gates: clean worktree → tests green → version bump → tag → build →
+# (optional) publish to PyPI.
+#
+# Usage:
+#   bash scripts/release.sh 0.2.2          # bump, tag, build
+#   bash scripts/release.sh 0.2.2 --publish # ... and upload to PyPI
+#
+# Publish needs a PyPI token: UV_PUBLISH_TOKEN in the env, or pass it
+# when prompted. Everything else runs fully offline.
+set -euo pipefail
+
+REPO="devskale/pulli"
+VERSION="${1:?usage: release.sh <version> [--publish] (no leading v)}"
+VERSION="${VERSION#v}"
+TAG="v$VERSION"
+PUBLISH="${2:-}"
+
+cd "$(dirname "$0")/.."
+
+echo "── Gate: clean worktree ──"
+if [ -n "$(git status --porcelain)" ]; then
+    echo "  worktree is dirty — commit or stash first:" >&2
+    git status --porcelain >&2
+    exit 1
+fi
+
+echo "── Gate: on main, up to date with origin ──"
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+[ "$BRANCH" = "main" ] || { echo "  not on main (is $BRANCH)" >&2; exit 1; }
+git fetch -q origin main
+[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] || {
+    echo "  main is not in sync with origin/main — push/pull first" >&2
+    exit 1
+}
+
+echo "── Gate: tag does not exist yet ──"
+git rev-parse -q --verify "refs/tags/$TAG" >/dev/null && {
+    echo "  $TAG already exists" >&2
+    exit 1
+}
+
+echo "── Gate: tests green ──"
+uv run --extra dev pytest
+
+echo "── Bump version → $VERSION ──"
+INIT="src/pulli/__init__.py"
+sed -i '' "s/^__version__ = .*/__version__ = \"$VERSION\"/" "$INIT"
+git add "$INIT" uv.lock
+git commit -q -m "v$VERSION" -m "Released via scripts/release.sh (local build, zero CI minutes)."
+git tag -a "$TAG" -m "v$VERSION"
+
+echo "── Sanity: built wheel reports the right version ──"
+rm -rf dist && mkdir -p dist
+uv build -q
+uv run --no-project --with "./dist/pulli-$VERSION-py3-none-any.whl" \
+    pulli --version | grep -Fx "pulli $VERSION" || {
+    echo "  version mismatch in wheel" >&2
+    exit 1
+}
+
+echo "── Push commit + tag ──"
+git push origin main "refs/tags/$TAG"
+
+if [ "$PUBLISH" = "--publish" ]; then
+    echo "── Publish to PyPI ──"
+    if [ -z "${UV_PUBLISH_TOKEN:-}" ]; then
+        echo "  UV_PUBLISH_TOKEN not set — get one at pypi.org (account settings"
+        echo "  → API tokens, scope: this project) and re-run with it set:"
+        echo "    UV_PUBLISH_TOKEN=pypi-... bash scripts/release.sh $VERSION --publish"
+        exit 1
+    fi
+    uv publish "dist/pulli-$VERSION-py3-none-any.whl" "dist/pulli-$VERSION.tar.gz"
+    echo "── Done: https://pypi.org/project/pulli/$VERSION ──"
+else
+    echo "── Built (not published). To publish: ──"
+    echo "    UV_PUBLISH_TOKEN=pypi-... uv publish dist/pulli-$VERSION*"
+fi

{pulli-0.2.1 → pulli-0.2.5}/src/pulli/__init__.py

@@ -1,2 +1,2 @@
 """pulli — discover git repos under a root and report their status."""
-__version__ = "0.2.1"
+__version__ = "0.2.5"