mark-twin 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bae405ea7916f59395530f5372cd3bde2aa4ff742ca4cf08142ca16be5c7cd9
-  data.tar.gz: b05b48d23901e7c6c2fd313ecc0f8ef2dbf172ab77ef38b5575088031dc186da
+  metadata.gz: 07baefa770954e6be785cd591c727fb287b7a64dcf84d4c83eb3c747978da7ba
+  data.tar.gz: d29597f8f7b20380b658bd9127c5a72f904f8baea2e3dd20756a7431317e53bd
 SHA512:
-  metadata.gz: 3d10977e33311149b1d90486c553cf6ce773c9c2927a081f3e264dcb9a8d0c97be61bb62883b070cb739ab66aa710d2d359b95db33018f8463bd0ac9987c0a95
-  data.tar.gz: ec1eecdf09d77e1c0ef6480edeb889c9d737b87cbd9eda5a9e83e210ca5fc2eeee85d06f86ccb65e81040197a8a4402001eeb79bda60710f44c77cd7e2e16c26
+  metadata.gz: 43c56ce8ed70a445dd3dabf803e68d25651cafe7b4a04e90f4202680592ac447345ab0f55e0dbd09970004d553c84868ae6aec6a643f48cd71f5d2583e0c20a4
+  data.tar.gz: 25043aaa4ddf2f30ed8b546f52e68dccd008493414a9c8447d44c2c36acc45d32e375977b0d8b927623d2e5d6e937f0b2b56ed28cb8be53c2eeedeea08c73871

data/README.md

@@ -4,12 +4,11 @@
 [![Tests](https://github.com/rhsev/mark-twin/actions/workflows/test.yml/badge.svg)](https://github.com/rhsev/mark-twin/actions/workflows/test.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Sync configuration between machines, from Markdown files that explain
-themselves.
+Sync configuration between Macs (or to any host you can reach over ssh) from
+self-documenting Markdown files.
 
-A sync-file is a normal Markdown document. The prose explains it to you — and
-to whatever assistant you point at the file later. The fenced YAML blocks are
-what twin acts on:
+A sync-file is a normal Markdown document. The prose is for you, or for an AI
+assistant. twin only uses the fenced YAML blocks:
 
 ````markdown
 ---
@@ -21,7 +20,7 @@ Target: admin@macbook:/Users/admin
 ## Fish Shell
 
 Shell config, including completions and abbreviations. `local.fish` stays
-machine-specific — the laptop keeps its own.
+machine-specific, the MacBook keeps its own.
 
 ```yaml
 Program: Fish Shell
@@ -31,29 +30,27 @@ Own: conf.d/local.fish
 ```
 ````
 
-`twin` then shows you what differs and syncs what you pick. Under the
-hood it is `rsync`; the point is the file above, which still tells you in a
-year *why* a path is synced, not just that it is.
+`twin` shows you what differs and syncs what you choose. At its core, it's just
+`rsync`, but a year later the file still tells you *why* you did it that way.
 
-That is the whole idea, and for most entries it stays exactly that small. The
-rest of this README is long because twin does handle the awkward cases — files
-the other machine owns, both sides changed since last time, paths that differ
-per host — not because you need any of them on day one. Skip what you don't
-need.
+That is the whole idea, and for most entries it stays as small as the excerpt
+above. The rest of this README is long because twin also covers more complex
+cases: files that are specific to the other computer, files that have changed
+on both sides since the last sync, and paths that differ per host.
 
 ## Why Markdown
 
-- **You can read it later.** The reason a path is synced lives next to the
-  path, in prose, not in a comment you stopped writing after the third entry.
+- **You can read it later.** The reason a path is synced sits next to the
+  path, in prose.
 - **Machines can read it too.** The YAML blocks are extracted by
   [grubber](https://github.com/rhsev/grubber), so the same file can feed other
   tools, not just twin.
 - **It stays editable by hand.** No generated state, no database. Add a block
   in your editor and twin picks it up.
-- **And yes, ask your AI to write them.** Markdown with YAML blocks is exactly
-  what language models are good at. Show one an existing sync-file, describe
-  the next entry, and what comes back is valid for grubber and still readable
-  by you — which is the whole bargain of this format.
+- **Ask your AI to help you write it.** Markdown with YAML blocks is what
+  language models are good at. Show this README and an existing sync-file,
+  describe the next entry, and what comes back is valid for grubber and still
+  readable by you.
 
 ## Screenshots
 
@@ -93,7 +90,7 @@ gem install ./mark-twin-*.gem
 
 ## Getting started
 
-**1. Decide where the other side lives.** `Target:` takes either form, and
+**1. Choose ssh or a mounted volume.** `Target:` takes either form, and
 neither is the special case:
 
 ```yaml
@@ -130,7 +127,7 @@ an editor — it finds the matching sync-file, derives the relative path,
 suggests excludes for what it sees in the directory, and appends a block with a
 prose stub.
 
-**4. Look before you leap:**
+**4. Check first:**
 
 ```bash
 twin status              # what differs
@@ -151,18 +148,50 @@ twin status                  # listing with source/target mtimes
 twin sync -p grubber         # sync one program by name pattern
 twin sync --file=repos       # sync all programs from a sync-file
 twin sync --dry-run          # preview without writing
+twin sync -v                 # rsync's full output instead of just the changes
 twin log                     # recent journal entries (-n N, --json)
 twin doctor                  # check tools, renderers, and targets
+twin --version               # which twin is actually running
 twin --help                  # show usage
 ```
 
 A file argument without `/` is matched by substring against sync-file names in
 `sync_dir`; anything containing `/` is treated as a path, file or directory.
 
+By default a sync prints only what changed — the lines below, plus anything a
+`Cmd` produced and any error. `-v` adds rsync's headers and transfer summaries
+back. The bare `twin` picker needs a terminal and says so instead of waiting
+when there is none, so cron jobs and `ssh host twin …` fail with a usable
+message rather than hanging.
+
 Every job is journaled to `~/.local/state/twin/log.jsonl` — one JSON line with
 timestamp, program, path and outcome. `twin sync` exits non-zero if any job
 failed.
 
+### Reading a dry-run
+
+`--dry-run` passes rsync's `--itemize-changes` through, which is precise but
+terse. The first two characters are what matter:
+
+| Line | Means |
+|---|---|
+| `>f+++++++++` | new file, does not exist on the target yet |
+| `>f.s.......` | `s` is set: the size differs, so the content really changed |
+| `>f..t......` | only `t`: same size, later timestamp — usually identical bytes |
+| `.f...p.....` | no transfer at all, permissions only |
+| `.d..tp.....` | a directory's own timestamp or permissions |
+| `*deleting` | removed on the target (`Delete: true` jobs) |
+
+Two rules cover most of it: a leading `>` means data would move and a leading
+`.` means it would not, and among the flags `s` is the one that proves the
+content changed rather than just a timestamp.
+
+Only the `>` and `*deleting` lines appear by default — the `.` ones are what
+`-v` adds back, along with rsync's headers and byte counts. So a job that
+prints nothing under its name moved nothing, and a run full of `>f..t......`
+lines is twin re-stamping files whose contents already match, which is normal
+after syncing a tree in both directions.
+
 ## Sync-files
 
 One Markdown file per relationship. Frontmatter sets it up, YAML blocks define
@@ -209,7 +238,7 @@ reports them apart:
 
 The distinction is documentation, not mechanism. Six months on, `Own:` still
 says "deliberate, the other machine maintains this", where the same entry sitting
-in `Exclude:` between `*.dwarf` and `.DS_Store` reads like noise you once
+in `Exclude:` between `*.dwarf` and `.DS_Store` is something you once
 filtered out.
 
 ### Cmd: doing something after a sync
@@ -262,6 +291,49 @@ Target: ralf@server:/srv/www
 ---
 ```
 
+## Two shapes of sync
+
+The mechanics are the same either way, but what you *mean* differs, and it
+decides how you should answer everything below.
+
+**A mirror.** Both machines are yours, both get worked on, and each direction
+is its own entry with `Source:` and `Target:` swapped. Neither side is more
+right than the other; a file being newer over there is ordinary, and the
+question is which version you want. This is what the two-Macs examples in this
+README describe.
+
+**A deploy.** One side is the truth and the other only runs it — a server, a
+container, a NAS. The rule that makes this work is short: *the target is never
+a source.* Nothing gets edited over there, so anything that shows up as a
+target-side change means the rule was broken, and that is worth stopping for
+rather than waving through.
+
+Write the rule into the sync-file itself, in the prose where the next person —
+you, in a year — will read it:
+
+````markdown
+---
+Active: 1
+Label: mini → dylan
+Source: /Volumes/lightning/Git/rhsev/dy.lan
+Target: /Volumes/docker/dylan
+---
+
+# Dylan
+
+Deploy to the container. **Work happens locally; the target is never a
+source.** A `target_newer` in `twin status` is therefore not a normal
+state — find out who edited over there before overwriting it.
+````
+
+The practical difference is which answer you pre-arrange for automation. On a
+mirror there is rarely a right answer in advance, so run those syncs by hand,
+or with `--skip-conflicts` and read the log. On a deploy `--force` matches the
+model — the source *is* the truth — but it discards a target-side edit without
+showing it to you first. That is precisely the trade the prompt exists to make
+deliberate, so prefer `--skip-conflicts` for scheduled runs and keep `--force`
+for the moment you have looked and decided.
+
 ## When the target has changed too
 
 A sync has a direction: the source wins. But targets get edited — a quick fix

data/lib/twin/cli.rb

@@ -24,12 +24,13 @@ module Twin
         twin list   [--all] [--label X] [--file X] [--json]
         twin status [--all] [--label X] [--file X] [--json]
         twin sync   [-p PATTERN] [--label X] [--file X] [--all] [--dry-run]
-                    [--quiet] [--skip-unavailable]
+                    [--quiet] [-v] [--skip-unavailable]
                     [--force] [--skip-conflicts]
         twin add <path>            scaffold a new sync entry for a local path
         twin log    [-n N] [--json]  recent journal entries (default 20)
         twin doctor                check tools, renderers, and sync targets
         twin --help                show this message
+        twin --version             show the running version
 
       FILE ARGUMENT:
         bare name (no /)  → matched by substring against sync-file names
@@ -63,6 +64,8 @@ module Twin
       when "doctor"   then cmd_doctor(cfg)
       when "-h", "--help", "help"
         puts USAGE
+      when "-V", "--version", "version"
+        puts "twin #{Twin::VERSION}"
       when /\A-/
         warn "unknown option: #{first}"
         warn "Run 'twin --help' for usage."
@@ -79,6 +82,17 @@ module Twin
     # ── picker → sync ──────────────────────────────────────────────────────────
 
     def pick_and_sync(cfg, file:)
+      # fzf without a terminal does not fail — it waits, silently, for input
+      # that will never come. Every unattended caller lands here: cron,
+      # `ssh host twin …`, an agent running commands. Say so and point at the
+      # command that does work.
+      unless $stdin.tty? && $stdout.tty?
+        warn "twin: the picker needs a terminal."
+        warn "      use `twin sync#{file ? " --file=#{file}" : ""}` for an unattended run" \
+             " (add --dry-run to preview)."
+        exit 1
+      end
+
       programs = Scanner.load_programs(cfg, file: file, show_all: false)
       if programs.empty?
         warn "no active programs found#{" in #{file}" if file}"
@@ -181,16 +195,18 @@ module Twin
         sync_jobs(cfg, p, p.active_jobs,
                   dry_run: opts[:dry_run], quiet: opts[:quiet],
                   skip_unavailable: opts[:skip_unavailable],
-                  force: opts[:force], skip_conflicts: opts[:skip_conflicts])
+                  force: opts[:force], skip_conflicts: opts[:skip_conflicts],
+                  verbose: opts[:verbose])
       end
       exit 1 unless results.all?
     end
 
     # Sync the given jobs. Returns true when every attempted job succeeded.
     # quiet:            print only conflicts, errors, and jobs that changed something
+    # verbose:          print rsync's full output instead of just the changes
     # skip_unavailable: skip jobs whose target is unmounted/unreachable instead of aborting
     def sync_jobs(cfg, program, jobs, dry_run: false, quiet: false, skip_unavailable: false,
-                  force: false, skip_conflicts: false)
+                  force: false, skip_conflicts: false, verbose: false)
       jobs = jobs.select { |j| j.active == 1 }
       return true if jobs.empty?
 
@@ -230,7 +246,8 @@ module Twin
           header_printed = true
         end
         puts "  • #{job.path}"
-        puts output.gsub(/^/, "    ") if output && !output.strip.empty?
+        shown = verbose || !success ? output : Twin::Sync.summarize(output.to_s)
+        puts shown.gsub(/^/, "    ") if shown && !shown.strip.empty?
         warn "  error syncing #{job.path}" unless success
       end
       all_ok
@@ -353,6 +370,11 @@ module Twin
     def cmd_doctor(cfg)
       ok = true
 
+      # First line, because "which version am I actually running" is the
+      # question behind a surprising number of the others.
+      puts "twin #{Twin::VERSION}"
+      puts
+
       puts "Tools"
       %w[grubber rsync fzf].each do |bin|
         if tool_available?(bin)
@@ -446,11 +468,13 @@ module Twin
 
     def parse_sync_opts(args)
       opts = { show_all: false, label: nil, file: nil, pattern: nil, dry_run: false,
-               quiet: false, skip_unavailable: false, force: false, skip_conflicts: false }
+               quiet: false, skip_unavailable: false, force: false, skip_conflicts: false,
+               verbose: false }
       OptionParser.new do |o|
         o.on("--all")          { opts[:show_all] = true }
         o.on("--label=L")      { |v| opts[:label] = v }
         o.on("--file=F")       { |v| opts[:file] = v }
+        o.on("-v", "--verbose")   { opts[:verbose] = true }
         o.on("--force")           { opts[:force] = true }
         o.on("--skip-conflicts")  { opts[:skip_conflicts] = true }
         o.on("-p", "--pattern=P") { |v| opts[:pattern] = v }

data/lib/twin/sync.rb

@@ -18,6 +18,29 @@ module Twin
       output.lines.any? { |l| ITEMIZE_CHANGE.match?(l) }
     end
 
+    # rsync's own noise: the header, the blank line, and the transfer summary.
+    # Everything twin adds itself (cmd output, "skipped:", error text) survives,
+    # as does any itemize line describing an actual change.
+    # Spaces are escaped on purpose: /x ignores literal whitespace, and these
+    # patterns are all multi-word.
+    RSYNC_NOISE = /
+      \A(sending|receiving)\ incremental\ file\ list\z |
+      \Acreated\ directory\  |
+      \Asent\ [\d,]+\ bytes |
+      \Atotal\ size\ is\ [\d,]+
+    /x
+
+    # Drop everything from an rsync run that does not describe a change.
+    # An itemize line whose first column is "." moved no data — permissions or
+    # a timestamp on an existing file — and is exactly the material that made
+    # the interesting lines hard to find.
+    def summarize(output)
+      output.lines.reject do |line|
+        l = line.rstrip
+        l.empty? || RSYNC_NOISE.match?(l) || (l.start_with?(".") && l =~ /\A\.[fdLDS]/)
+      end.join
+    end
+
     # True if the path lives on a mounted volume other than the root filesystem.
     # Walks up parents until it finds a mount point (different device than parent)
     # or hits "/" (path is on the root volume, not externally mounted).

data/lib/twin/version.rb

@@ -1,3 +1,3 @@
 module Twin
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mark-twin
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Ralf Hülsmann
@@ -23,8 +23,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: twin reads sync-files (Markdown + YAML blocks) via grubber, groups them
-  by program, and runs rsync. Interactive picker uses fzf with an apex Markdown preview.
+description: |
+  Keeping two machines' configuration aligned usually ends in a shell script
+  nobody dares touch, because the reasons behind it were never written down.
+
+  twin puts the reasons and the instructions in the same file. A sync-file is
+  ordinary Markdown: the prose explains why a path is synced, and fenced YAML
+  blocks say what to do. rsync does the copying.
+
+  It knows the awkward parts. Paths the other machine owns stay untouched and
+  are named as such, not buried among build artefacts. When both sides changed
+  since the last sync, twin shows a diff and asks before overwriting anything,
+  once for the whole group, so a half-applied deploy is not a state it can
+  leave you in. Targets are a local path, a mounted volume, or user@host:/path
+  over ssh, with no difference in how they are used.
+
+  Interactive selection runs through fzf with a rendered Markdown preview; the
+  same sync-files drive scriptable status, dry-run and sync commands.
 email:
 - huelsmann@sevelen.net
 executables:
@@ -55,6 +70,8 @@ licenses:
 metadata:
   source_code_uri: https://github.com/rhsev/mark-twin
   bug_tracker_uri: https://github.com/rhsev/mark-twin/issues
+  changelog_uri: https://github.com/rhsev/mark-twin/releases
+  documentation_uri: https://github.com/rhsev/mark-twin#readme
 post_install_message: |2+
 
   twin requires these external tools in your PATH:
@@ -82,6 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.4
 specification_version: 4
-summary: Sync configuration between machines, from self-documenting Markdown files
+summary: Sync configuration between Macs and any ssh host, from self-documenting Markdown
+  files
 test_files: []
 ...