@kova1/pullr 0.3.1 → 0.4.0

package/README.md

@@ -12,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)
@@ -32,6 +32,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 +46,24 @@ 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 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
 
 ```
@@ -53,25 +77,15 @@ 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:
-
-- 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.
+### 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.
 
 ### Dry run
 
@@ -97,17 +111,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.4.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=""
@@ -121,7 +126,7 @@ pull_repo() {
     "$(update_note "$n" "$local_n" rebased)" "$reset"
 }
 
-# "N new commit(s)[, M rebased|to rebase]"
+# "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)"

package/package.json

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