@kova1/pullr 0.3.1 → 0.5.0

package/README.md

@@ -12,13 +12,15 @@ everything current means `cd`-ing into each one.
 
 ```console
 $ pullr ~/work
-+ api (main, 3 new commit(s))
++ api (main, 3 new commits)
 = web (main)
+~ docs (main, 2 commits held back by local changes)
 - scratch (main has no upstream)
 x infra (main)
-    fatal: Not possible to fast-forward, aborting.
+    diverged from upstream (behind 2, ahead 1): cannot fast-forward
 
-Repos: 4  updated: 1  up to date: 1  skipped: 1  failed: 1
+Repos: 5  updated: 1  up to date: 1  dirty: 1  skipped: 1  failed: 1
+Dirty: docs
 Failed: infra
 ```
 
@@ -32,6 +34,12 @@ brew install kova1max/tap/pullr
 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`.
 
@@ -40,6 +48,26 @@ Every release is also mirrored to
 `@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, overwrite or discard your changes.** There is no auto-stash. If
+  local edits or untracked files are in the way of incoming changes, the
+  repository is reported as dirty and left as it was; edits that don't touch
+  incoming files don't stop the update.
+- **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
 
 ```
@@ -53,25 +81,17 @@ pullr [options] [DIR]
 | `--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:
+### Output
 
-- 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.
-  With `--rebase`, that branch's local commits are rebased onto the upstream
-  instead, and the line reads `+ api (main, 3 new commits, 2 rebased)`. There
-  is no auto-stash: a dirty tree makes git refuse the rebase, which is
-  reported as failed.
-- 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.
-
-Each repository gets one line: `+` updated, `=` already up to date, `-`
-skipped, `x` failed (with git's output indented below it).
+Each repository gets one line: `+` updated, `=` already up to date, `~`
+dirty (local changes are in the way of the update, which is held back), `-`
+skipped, `x` failed (with the reason indented below it). Exits `1` if any
+pull failed, `2` on invalid arguments, `0` otherwise; a dirty repository is
+not a failure.
 
 ### Dry run
 
@@ -86,7 +106,7 @@ 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
+Repos: 4  would update: 1  up to date: 1  dirty: 0  skipped: 1  would fail: 1
 Failed: infra
 ```
 
@@ -97,17 +117,6 @@ remote as it is now, then prints the same lines a real run would (with
 only updates remote-tracking refs: the working tree and current branch are
 never modified. Exit codes match a real run.
 
-## Development
-
-```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
-```
-
-Releases are cut by GitHub Actions - see [RELEASE.md](RELEASE.md).
-
 ## License
 
 [MIT](LICENSE)

package/bin/pullr

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 # Recursively find git repos under a directory and fast-forward pull each one.
-# Usage: pullr [--jobs N] [--max-depth N] [--dry-run] [--rebase] [DIR]
+# Usage: pullr [--jobs N] [--max-depth N] [--dry-run] [--rebase] [--no-color] [DIR]
 set -euo pipefail
 
-VERSION="0.3.1" # set by the release workflow
+VERSION="0.5.0" # set by the release workflow
 
 usage() {
   cat <<'EOF'
@@ -24,6 +24,8 @@ Options:
                      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
@@ -32,6 +34,7 @@ EOF
 mode=pull
 jobs=4
 rebase=0
+color=1
 max_depth=2
 root=""
 
@@ -43,6 +46,7 @@ while (($#)); do
     --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 ;;
@@ -58,7 +62,8 @@ 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=""
@@ -79,96 +84,133 @@ indented() {
   printf '    %s\n' "${1//$'\n'/$'\n'    }"
 }
 
-pull_repo() {
-  local repo="$1" rel branch
-  rel="$(repo_label "$repo")"
-
+# Shared first half of a pull and a dry run: check the branch, fetch, and
+# count commits. On success it sets the caller's branch, behind and ahead;
+# otherwise it prints the result line and returns 1.
+prepare() {
+  local repo="$1" rel="$2" out counts
   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
+    return 1
   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
+    return 1
   fi
-
-  local before after out how=--ff-only
-  [[ "$rebase" == 0 ]] || how=--rebase
-  before="$(git -C "$repo" rev-parse HEAD)"
-  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"
-    indented "$out"
-    return
+  if ! out="$(git -C "$repo" fetch --quiet 2>&1)"; then
+    report_failed "$rel" "$branch" "$out"
+    return 1
   fi
-  after="$(git -C "$repo" rev-parse HEAD)"
+  counts="$(git -C "$repo" rev-list --left-right --count '@{upstream}...HEAD')"
+  behind="${counts%%[[:space:]]*}"
+  ahead="${counts##*[[:space:]]}"
+}
 
-  if [[ "$before" == "$after" ]]; then
-    echo current
-    printf '%s=%s %s %s(%s)%s\n' "$dim" "$reset" "$rel" "$dim" "$branch" "$reset"
-    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')"
+report_failed() {
+  printf 'failed\t%s\n' "$1"
+  printf '%sx%s %s %s(%s)%s\n' "$red" "$reset" "$1" "$dim" "$2" "$reset"
+  indented "$3"
+}
+
+report_diverged() {
+  report_failed "$1" "$2" "diverged from upstream (behind $3, ahead $4): cannot fast-forward"
+}
+
+report_dirty() {
+  printf 'dirty\t%s\n' "$1"
+  printf '%s~%s %s %s(%s, %s held back by local changes)%s\n' \
+    "$yellow" "$reset" "$1" "$dim" "$2" "$(commits "$3")" "$reset"
+}
+
+report_current() {
+  echo current
+  printf '%s=%s %s %s(%s)%s\n' "$dim" "$reset" "$1" "$dim" "$2" "$reset"
+}
+
+report_updated() {
+  local note
+  note="$3 new commit$([[ "$3" == 1 ]] || printf s)"
+  [[ "$4" == 0 ]] || note+=", $4 $5"
   echo updated
-  printf '%s+%s %s %s(%s, %s)%s\n' "$green" "$reset" "$rel" "$dim" "$branch" \
-    "$(update_note "$n" "$local_n" rebased)" "$reset"
+  printf '%s+%s %s %s(%s, %s)%s\n' "$green" "$reset" "$1" "$dim" "$2" "$note" "$reset"
 }
 
-# "N new commit(s)[, M rebased|to rebase]"
-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"
+# "1 commit", "3 commits"
+commits() {
+  printf '%s commit%s' "$1" "$([[ "$1" == 1 ]] || printf s)"
 }
 
-dryrun_repo() {
-  local repo="$1" rel branch
+# Uncommitted changes to tracked files, staged or not.
+has_tracked_changes() {
+  ! git -C "$1" diff --quiet HEAD --
+}
+
+pull_repo() {
+  local repo="$1" rel branch behind ahead out
   rel="$(repo_label "$repo")"
+  prepare "$repo" "$rel" || return 0
 
-  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
+  if [[ "$behind" == 0 ]]; then
+    report_current "$rel" "$branch"
+  elif [[ "$ahead" == 0 ]]; then
+    # git refuses, touching nothing, when local changes are in the way
+    if out="$(git -C "$repo" merge --ff-only --quiet '@{upstream}' 2>&1)"; then
+      report_updated "$rel" "$branch" "$behind" 0 ""
+    elif [[ -n "$(git -C "$repo" status --porcelain)" ]]; then
+      report_dirty "$rel" "$branch" "$behind"
+    else
+      report_failed "$rel" "$branch" "$out"
+    fi
+  elif [[ "$rebase" == 0 ]]; then
+    report_diverged "$rel" "$branch" "$behind" "$ahead"
+  elif has_tracked_changes "$repo"; then
+    report_dirty "$rel" "$branch" "$behind"
+  elif out="$(git -C "$repo" rebase --quiet '@{upstream}' 2>&1)"; then
+    report_updated "$rel" "$branch" "$behind" "$ahead" rebased
+  else
+    # A rebase that stopped on a conflict must not leave the repository
+    # mid-rebase; --abort succeeds only when one is in progress.
+    if git -C "$repo" rebase --abort >/dev/null 2>&1; then
+      report_failed "$rel" "$branch" "$out"
+    elif [[ -n "$(git -C "$repo" status --porcelain)" ]]; then
+      report_dirty "$rel" "$branch" "$behind"
+    else
+      report_failed "$rel" "$branch" "$out"
+    fi
   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
+# Would local changes stop a fast-forward? Git refuses when a file it has to
+# update is modified locally or exists untracked, so compare the two lists.
+changes_block_update() {
+  local repo="$1" incoming local_paths
+  incoming="$(git -C "$repo" diff --name-only HEAD '@{upstream}')"
+  local_paths="$(git -C "$repo" status --porcelain --untracked-files=all | cut -c4-)"
+  [[ -n "$incoming" && -n "$local_paths" ]] || return 1
+  printf '%s\n' "$local_paths" | grep -qFxf <(printf '%s\n' "$incoming")
+}
 
-  local counts behind ahead
-  counts="$(git -C "$repo" rev-list --left-right --count '@{upstream}...HEAD')"
-  behind="${counts%%[[:space:]]*}"
-  ahead="${counts##*[[:space:]]}"
+dryrun_repo() {
+  local repo="$1" rel branch behind ahead
+  rel="$(repo_label "$repo")"
+  prepare "$repo" "$rel" || return 0
 
-  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"
+  if [[ "$behind" == 0 ]]; then
+    report_current "$rel" "$branch"
+  elif [[ "$ahead" == 0 ]]; then
+    if changes_block_update "$repo"; then
+      report_dirty "$rel" "$branch" "$behind"
+    else
+      report_updated "$rel" "$branch" "$behind" 0 ""
+    fi
+  elif [[ "$rebase" == 0 ]]; then
+    report_diverged "$rel" "$branch" "$behind" "$ahead"
+  elif has_tracked_changes "$repo"; then
+    report_dirty "$rel" "$branch" "$behind"
   else
-    echo current
-    printf '%s=%s %s %s(%s)%s\n' "$dim" "$reset" "$rel" "$dim" "$branch" "$reset"
+    report_updated "$rel" "$branch" "$behind" "$ahead" "to rebase"
   fi
 }
 
@@ -209,8 +251,8 @@ fi
 
 [[ "$mode" != dryrun ]] || printf '%sDry run: nothing will be pulled.%s\n' "$dim" "$reset"
 
-updated=0 current=0 skipped=0 failed=0
-failed_repos=()
+updated=0 current=0 skipped=0 failed=0 dirty=0
+failed_repos=() dirty_repos=()
 
 consume() {
   local text="$1" head="${1%%$'\n'*}" body="${1#*$'\n'}"
@@ -219,6 +261,7 @@ consume() {
     updated) updated=$((updated + 1)) ;;
     current) current=$((current + 1)) ;;
     skipped) skipped=$((skipped + 1)) ;;
+    dirty) dirty=$((dirty + 1)); dirty_repos+=("$label") ;;
     failed) failed=$((failed + 1)); failed_repos+=("$label") ;;
     *) echo "pullr: unexpected worker result: $text" >&2; exit 1 ;;
   esac
@@ -230,7 +273,7 @@ if ((jobs > 1 && count > 1)); then
   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
+  export -f worker pull_repo dryrun_repo repo_label indented prepare report_failed report_diverged report_dirty report_current report_updated commits has_tracked_changes changes_block_update
   # 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" &
@@ -255,12 +298,13 @@ fi
 
 echo
 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"
+  printf 'Repos: %d  %swould update: %d%s  up to date: %d  %sdirty: %d  skipped: %d%s  %swould fail: %d%s\n' \
+    "$count" "$green" "$updated" "$reset" "$current" "$yellow" "$dirty" "$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"
+  printf 'Repos: %d  %supdated: %d%s  up to date: %d  %sdirty: %d  skipped: %d%s  %sfailed: %d%s\n' \
+    "$count" "$green" "$updated" "$reset" "$current" "$yellow" "$dirty" "$skipped" "$reset" "$red" "$failed" "$reset"
 fi
+((dirty == 0)) || printf 'Dirty: %s\n' "${dirty_repos[*]}"
 if ((failed)); then
   printf 'Failed: %s\n' "${failed_repos[*]}"
   exit 1

package/package.json

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