@kova1/pullr 0.1.0 → 0.4.0

package/README.md

@@ -1,5 +1,10 @@
 # pullr
 
+[![CI](https://github.com/kova1max/pullr/actions/workflows/ci.yml/badge.svg)](https://github.com/kova1max/pullr/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40kova1%2Fpullr?logo=npm&label=npm)](https://www.npmjs.com/package/@kova1/pullr)
+[![Homebrew](https://img.shields.io/github/v/release/kova1max/pullr?logo=homebrew&label=homebrew)](https://github.com/kova1max/homebrew-tap)
+[![License: MIT](https://img.shields.io/github/license/kova1max/pullr)](LICENSE)
+
 Fast-forward pull every git repository under a directory.
 
 Built for workspaces made of many independent repositories, where keeping
@@ -7,7 +12,7 @@ everything current means `cd`-ing into each one.
 
 ```console
 $ pullr ~/work
-+ api (main, 3 new commit(s))
++ api (main, 3 new commits)
 = web (main)
 - scratch (main has no upstream)
 x infra (main)
@@ -21,51 +26,90 @@ Failed: infra
 
 ```sh
 # Homebrew
-brew install kova1max/tap/pullr   # after that, plain `pullr` works too
+brew install kova1max/tap/pullr
 
 # npm
 npm install -g @kova1/pullr
 ```
 
+To try it without installing anything:
+
+```sh
+npx @kova1/pullr --dry-run ~/work
+```
+
 Or copy [`bin/pullr`](bin/pullr) anywhere on your `PATH` - it is a single bash
 script with no dependencies beyond `git`.
 
+Every release is also mirrored to
+[GitHub Packages](https://github.com/kova1max/pullr/pkgs/npm/pullr) as
+`@kova1max/pullr` (GitHub requires the repo owner as scope). Installing from
+there needs a GitHub token, so the npm registry above is the easier choice.
+
+## What it will never do
+
+pullr is built to be safe to run across a whole workspace without looking
+first. It will never:
+
+- **Create a merge commit.** Pulls are fast-forward only.
+- **Touch a branch that has diverged** from its upstream. It is reported as
+  failed and left exactly as it was. Rebasing it is opt-in with `--rebase`,
+  and a rebase that hits a conflict is aborted, leaving the repository as it
+  was.
+- **Stash or discard your changes.** There is no auto-stash; if git refuses
+  to update a dirty working tree, the repository is reported as failed.
+- **Touch a repository on a detached `HEAD`**, or a branch with no upstream.
+  Both are skipped.
+- **Enter a nested repository.** Repositories inside another repository,
+  including submodules, are left to their parent.
+- **Follow symlinked directories.**
+
 ## Usage
 
 ```
-pullr [--max-depth N] [DIR]
+pullr [options] [DIR]
 ```
 
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `DIR` | current directory | Where to look for repositories |
+| `-j`, `--jobs N` | `4` | Work on up to `N` repositories in parallel. Output is buffered per repository and printed in discovery order, so it reads the same as a sequential run. With `N > 1` git never prompts for credentials; use `--jobs 1` for repositories that need an interactive login. |
 | `--max-depth N` | `2` | How many directory levels below `DIR` to search. `0` = only `DIR` itself, `1` = `DIR` and its direct children, ... |
+| `-n`, `--dry-run` | | Show what a run would do without pulling, see below |
+| `-r`, `--rebase` | off | Rebase local commits onto the upstream instead of refusing a diverged branch (`git pull --rebase`). A rebase that hits a conflict is aborted and the repository is left as it was. |
+| `--no-color` | | Disable colored output. Also disabled when the [`NO_COLOR`](https://no-color.org) environment variable is set, or when output is not a terminal. |
 | `-V`, `--version` | | Print the version |
 | `-h`, `--help` | | Show help |
 
-Behaviour:
-
-- Runs `git pull --ff-only`, so it never creates merge commits. A branch that
-  has diverged from its upstream is reported as failed and left untouched.
-- Does not descend into a repository once found - nested repositories and
-  submodules are left to their parent.
-- Skips repositories on a detached `HEAD` and branches with no upstream.
-- Does not follow symlinked directories.
-- Exits `1` if any pull failed, `2` on invalid arguments, `0` otherwise.
+### Output
 
 Each repository gets one line: `+` updated, `=` already up to date, `-`
-skipped, `x` failed (with git's output indented below it).
+skipped, `x` failed (with git's output indented below it). Exits `1` if any
+pull failed, `2` on invalid arguments, `0` otherwise.
 
-## Development
+### Dry run
 
-```sh
-npm install     # installs bats
-npm test        # end-to-end tests against real temporary git repos
-npm run lint    # shellcheck
-PULLR_BASH=/bin/bash npm test   # run the suite under macOS's bash 3.2
+`pullr --dry-run` shows what a run would do, without pulling:
+
+```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  skipped: 1  would fail: 1
+Failed: infra
 ```
 
-Releases are cut by GitHub Actions - see [RELEASE.md](RELEASE.md).
+It runs `git fetch` in each repository first, so the answer reflects the
+remote as it is now, then prints the same lines a real run would (with
+`--rebase`, a diverged repository shows as `+ ... , 2 to rebase` instead of
+`x`; whether the rebase 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.
 
 ## License
 

package/bin/pullr

@@ -1,32 +1,52 @@
 #!/usr/bin/env bash
 # Recursively find git repos under a directory and fast-forward pull each one.
-# Usage: pullr [--max-depth N] [DIR]
+# Usage: pullr [--jobs N] [--max-depth N] [--dry-run] [--rebase] [--no-color] [DIR]
 set -euo pipefail
 
-VERSION="0.1.0" # set by the release workflow
+VERSION="0.4.0" # set by the release workflow
 
 usage() {
   cat <<'EOF'
-Usage: pullr [--max-depth N] [DIR]
+Usage: pullr [options] [DIR]
 
 Finds git repositories under DIR (default: current directory) and runs
 `git pull --ff-only` in each. Does not descend into a repository once found.
 
 Options:
-  --max-depth N   How many directory levels below DIR to search (default: 2).
-                  0 = only DIR itself, 1 = DIR and its direct children, ...
-  -V, --version   Print the version.
-  -h, --help      Show this help.
+  -j, --jobs N       Work on up to N repositories in parallel (default: 4).
+                     Output is buffered per repository and printed in order.
+                     With N > 1 git never prompts for credentials.
+      --max-depth N  How many directory levels below DIR to search (default: 2).
+                     0 = only DIR itself, 1 = DIR and its direct children, ...
+  -n, --dry-run      Fetch, then show what a run would do to each repository
+                     without pulling anything.
+  -r, --rebase       Rebase local commits onto the upstream instead of
+                     refusing a branch that has diverged (git pull --rebase).
+                     A rebase that hits a conflict is aborted, leaving the
+                     repository as it was.
+      --no-color     Disable colored output. Also disabled when NO_COLOR is
+                     set (https://no-color.org) or output is not a terminal.
+  -V, --version      Print the version.
+  -h, --help         Show this help.
 EOF
 }
 
+mode=pull
+jobs=4
+rebase=0
+color=1
 max_depth=2
 root=""
 
 while (($#)); do
   case "$1" in
+    -j|--jobs) jobs="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
+    --jobs=*) jobs="${1#*=}"; shift ;;
     --max-depth) max_depth="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
     --max-depth=*) max_depth="${1#*=}"; shift ;;
+    -n|--dry-run) mode=dryrun; shift ;;
+    -r|--rebase) rebase=1; shift ;;
+    --no-color) color=0; shift ;;
     -h|--help) usage; exit 0 ;;
     -V|--version) echo "pullr $VERSION"; exit 0 ;;
     -*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
@@ -36,58 +56,143 @@ while (($#)); do
   esac
 done
 
+[[ "$jobs" =~ ^[1-9][0-9]*$ ]] || { echo "--jobs must be a positive integer" >&2; exit 2; }
 [[ "$max_depth" =~ ^[0-9]+$ ]] || { echo "--max-depth must be a non-negative integer" >&2; exit 2; }
 root="${root:-.}"
 [[ -d "$root" ]] || { echo "Not a directory: $root" >&2; exit 2; }
 root="$(cd "$root" && pwd)"
 
-if [[ -t 1 ]]; then
+# https://no-color.org: any non-empty NO_COLOR disables color
+if [[ "$color" == 1 && -z "${NO_COLOR:-}" && -t 1 ]]; then
   green=$'\e[32m' yellow=$'\e[33m' red=$'\e[31m' dim=$'\e[2m' reset=$'\e[0m'
 else
   green="" yellow="" red="" dim="" reset=""
 fi
 
-updated=0 current=0 skipped=0 failed=0
-failed_repos=()
+# --- per-repository work -----------------------------------------------------
+# Each *_repo function prints a result: the first line is the category used
+# for the summary, the rest is what the user sees. That shape lets the same
+# functions run inline or inside a worker whose output is buffered to a file.
+
+repo_label() {
+  local rel="${1#"$root"}"
+  rel="${rel#/}"
+  printf '%s' "${rel:-.}"
+}
+
+indented() {
+  printf '    %s\n' "${1//$'\n'/$'\n'    }"
+}
 
 pull_repo() {
-  local repo="$1" rel="${1#"$root"}"
-  rel="${rel#/}"; rel="${rel:-.}"
+  local repo="$1" rel branch
+  rel="$(repo_label "$repo")"
 
-  local branch
   if ! branch="$(git -C "$repo" symbolic-ref --quiet --short HEAD)"; then
+    echo skipped
     printf '%s-%s %s %s(detached HEAD)%s\n' "$yellow" "$reset" "$rel" "$dim" "$reset"
-    skipped=$((skipped + 1)); return
+    return
   fi
   if ! git -C "$repo" rev-parse --quiet --verify '@{upstream}' >/dev/null 2>&1; then
+    echo skipped
     printf '%s-%s %s %s(%s has no upstream)%s\n' "$yellow" "$reset" "$rel" "$dim" "$branch" "$reset"
-    skipped=$((skipped + 1)); return
+    return
   fi
 
-  local before after out
+  local before after out how=--ff-only
+  [[ "$rebase" == 0 ]] || how=--rebase
   before="$(git -C "$repo" rev-parse HEAD)"
-  if ! out="$(git -C "$repo" pull --ff-only 2>&1)"; then
+  if ! out="$(git -C "$repo" pull "$how" 2>&1)"; then
+    # a conflicting rebase must not leave the repository mid-rebase
+    [[ "$rebase" == 0 ]] || git -C "$repo" rebase --abort >/dev/null 2>&1 || true
+    printf 'failed\t%s\n' "$rel"
     printf '%sx%s %s %s(%s)%s\n' "$red" "$reset" "$rel" "$dim" "$branch" "$reset"
-    printf '    %s\n' "${out//$'\n'/$'\n'    }"
-    failed=$((failed + 1)); failed_repos+=("$rel"); return
+    indented "$out"
+    return
   fi
   after="$(git -C "$repo" rev-parse HEAD)"
 
   if [[ "$before" == "$after" ]]; then
+    echo current
     printf '%s=%s %s %s(%s)%s\n' "$dim" "$reset" "$rel" "$dim" "$branch" "$reset"
-    current=$((current + 1))
+    return
+  fi
+  # New upstream commits, and (after a rebase) local commits now on top of them.
+  local n local_n=0
+  n="$(git -C "$repo" rev-list --count "$before..@{upstream}")"
+  [[ "$rebase" == 0 ]] || local_n="$(git -C "$repo" rev-list --count '@{upstream}..HEAD')"
+  echo updated
+  printf '%s+%s %s %s(%s, %s)%s\n' "$green" "$reset" "$rel" "$dim" "$branch" \
+    "$(update_note "$n" "$local_n" rebased)" "$reset"
+}
+
+# "N new commits[, M rebased|to rebase]", singular when N is 1
+update_note() {
+  local n="$1" local_n="$2" verb="$3" note
+  note="$n new commit$([[ "$n" == 1 ]] || printf s)"
+  [[ "$local_n" == 0 ]] || note+=", $local_n $verb"
+  printf '%s' "$note"
+}
+
+dryrun_repo() {
+  local repo="$1" rel branch
+  rel="$(repo_label "$repo")"
+
+  if ! branch="$(git -C "$repo" symbolic-ref --quiet --short HEAD)"; then
+    echo skipped
+    printf '%s-%s %s %s(detached HEAD)%s\n' "$yellow" "$reset" "$rel" "$dim" "$reset"
+    return
+  fi
+  if ! git -C "$repo" rev-parse --quiet --verify '@{upstream}' >/dev/null 2>&1; then
+    echo skipped
+    printf '%s-%s %s %s(%s has no upstream)%s\n' "$yellow" "$reset" "$rel" "$dim" "$branch" "$reset"
+    return
+  fi
+
+  local out
+  if ! out="$(git -C "$repo" fetch --quiet 2>&1)"; then
+    printf 'failed\t%s\n' "$rel"
+    printf '%sx%s %s %s(%s)%s\n' "$red" "$reset" "$rel" "$dim" "$branch" "$reset"
+    indented "$out"
+    return
+  fi
+
+  local counts behind ahead
+  counts="$(git -C "$repo" rev-list --left-right --count '@{upstream}...HEAD')"
+  behind="${counts%%[[:space:]]*}"
+  ahead="${counts##*[[:space:]]}"
+
+  if [[ "$behind" != 0 && "$ahead" != 0 && "$rebase" == 0 ]]; then
+    printf 'failed\t%s\n' "$rel"
+    printf '%sx%s %s %s(%s)%s\n' "$red" "$reset" "$rel" "$dim" "$branch" "$reset"
+    indented "diverged from upstream (behind $behind, ahead $ahead): cannot fast-forward"
+  elif [[ "$behind" != 0 ]]; then
+    # without --rebase this branch is only reached when ahead is 0
+    echo updated
+    printf '%s+%s %s %s(%s, %s)%s\n' "$green" "$reset" "$rel" "$dim" "$branch" \
+      "$(update_note "$behind" "$ahead" "to rebase")" "$reset"
   else
-    local n
-    n="$(git -C "$repo" rev-list --count "$before..$after")"
-    printf '%s+%s %s %s(%s, %s new commit(s))%s\n' "$green" "$reset" "$rel" "$dim" "$branch" "$n" "$reset"
-    updated=$((updated + 1))
+    echo current
+    printf '%s=%s %s %s(%s)%s\n' "$dim" "$reset" "$rel" "$dim" "$branch" "$reset"
   fi
 }
 
+# Runs inside the worker pool: $1 = scratch dir, $2 = index, $3 = repo.
+# The result file appears atomically (write, then rename) so the collector
+# can print results in order as they land.
+worker() {
+  exec </dev/null
+  "${mode}_repo" "$3" >"$1/$2.tmp" 2>&1 || true
+  mv "$1/$2.tmp" "$1/$2.done"
+}
+
+# --- discovery ---------------------------------------------------------------
+
+repos=()
 walk() {
   local dir="$1" depth="$2"
   if [[ -e "$dir/.git" ]]; then
-    pull_repo "$dir"
+    repos+=("$dir")
     return
   fi
   ((depth < max_depth)) || return 0
@@ -97,18 +202,70 @@ walk() {
     walk "${child%/}" $((depth + 1))
   done
 }
-
 walk "$root" 0
 
-total=$((updated + current + skipped + failed))
-if ((total == 0)); then
+count=${#repos[@]}
+if ((count == 0)); then
   echo "No git repositories found under $root (max depth $max_depth)"
   exit 0
 fi
 
+# --- collection --------------------------------------------------------------
+
+[[ "$mode" != dryrun ]] || printf '%sDry run: nothing will be pulled.%s\n' "$dim" "$reset"
+
+updated=0 current=0 skipped=0 failed=0
+failed_repos=()
+
+consume() {
+  local text="$1" head="${1%%$'\n'*}" body="${1#*$'\n'}"
+  local category="${head%%$'\t'*}" label="${head#*$'\t'}"
+  case "$category" in
+    updated) updated=$((updated + 1)) ;;
+    current) current=$((current + 1)) ;;
+    skipped) skipped=$((skipped + 1)) ;;
+    failed) failed=$((failed + 1)); failed_repos+=("$label") ;;
+    *) echo "pullr: unexpected worker result: $text" >&2; exit 1 ;;
+  esac
+  printf '%s\n' "$body"
+}
+
+if ((jobs > 1 && count > 1)); then
+  scratch="$(mktemp -d)"
+  trap 'rm -rf "$scratch"' EXIT
+  export GIT_TERMINAL_PROMPT=0
+  export mode rebase root green yellow red dim reset
+  export -f worker pull_repo dryrun_repo repo_label indented update_note
+  # shellcheck disable=SC2016  # the single-quoted body runs inside the child shell
+  for ((i = 0; i < count; i++)); do printf '%s\0%s\0' "$i" "${repos[i]}"; done |
+    xargs -0 -n 2 -P "$jobs" "$BASH" -c 'worker "$@"' _ "$scratch" &
+  pool=$!
+  trap 'kill "$pool" 2>/dev/null; rm -rf "$scratch"; exit 130' INT TERM
+  for ((i = 0; i < count; i++)); do
+    until [[ -e "$scratch/$i.done" ]]; do
+      if ! kill -0 "$pool" 2>/dev/null && [[ ! -e "$scratch/$i.done" ]]; then
+        echo "pullr: worker pool exited before finishing $(repo_label "${repos[i]}")" >&2
+        exit 1
+      fi
+      sleep 0.1
+    done
+    consume "$(cat "$scratch/$i.done")"
+  done
+  wait "$pool" || true
+else
+  for repo in "${repos[@]}"; do
+    consume "$("${mode}_repo" "$repo")"
+  done
+fi
+
 echo
-printf 'Repos: %d  %supdated: %d%s  up to date: %d  %sskipped: %d%s  %sfailed: %d%s\n' \
-  "$total" "$green" "$updated" "$reset" "$current" "$yellow" "$skipped" "$reset" "$red" "$failed" "$reset"
+if [[ "$mode" == dryrun ]]; then
+  printf 'Repos: %d  %swould update: %d%s  up to date: %d  %sskipped: %d%s  %swould fail: %d%s\n' \
+    "$count" "$green" "$updated" "$reset" "$current" "$yellow" "$skipped" "$reset" "$red" "$failed" "$reset"
+else
+  printf 'Repos: %d  %supdated: %d%s  up to date: %d  %sskipped: %d%s  %sfailed: %d%s\n' \
+    "$count" "$green" "$updated" "$reset" "$current" "$yellow" "$skipped" "$reset" "$red" "$failed" "$reset"
+fi
 if ((failed)); then
   printf 'Failed: %s\n' "${failed_repos[*]}"
   exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kova1/pullr",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Fast-forward pull every git repository under a directory",
   "keywords": [
     "git",