slipway 0.1.0

data/lib/slipway/git/fast_forwarding.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Slipway
+  module Git
+    class Repository
+      # A write to a working tree, and the checks and refusals around it. It runs through
+      # Repository's own runner, status and in-progress lookup.
+      module FastForwarding
+        UPSTREAM = '@{upstream}'
+        REFLOG_ACTION = 'slipway sync'
+        REFLOG_VARIABLE = 'GIT_REFLOG_ACTION'
+        # Abbreviations are refused: one that is unique today can name two commits tomorrow.
+        OBJECT_NAME = /\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/
+        # --no-autostash overrides merge.autoStash, under which git would stash local changes and
+        # leave a conflicted tree behind when they no longer apply. --no-overwrite-ignore: by
+        # default git replaces or removes an ignored file that stands in the way of an incoming
+        # path, and that content was never committed.
+        MERGE_ARGS = %w[merge --ff-only --no-stat --quiet --no-autostash --no-overwrite-ignore].freeze
+        UNKNOWN_REVISION = 'unknown revision'
+        # Git's refusals under LC_ALL=C. Each leaves the branch, the index and the working tree as
+        # they were.
+        REFUSALS = {
+          /^(?:error|fatal): Unable to create '.*index\.lock': File exists/ => Busy,
+          /^error: The following untracked working tree files would be (?:overwritten|removed)/ => WouldOverwrite,
+          /^error: Untracked working tree file '.*' would be (?:overwritten|removed)/ => WouldOverwrite,
+          /^error: Updating the following directories would lose untracked files/ => WouldOverwrite,
+          /^error: Updating '.*' would lose untracked files in it/ => WouldOverwrite,
+          /^error: Your local changes to the following files would be overwritten/ => WouldLoseChanges,
+          /^error: Entry '.*' not uptodate\. Cannot merge/ => WouldLoseChanges,
+          /^fatal: Not possible to fast-forward/ => NotFastForward
+        }.freeze
+
+        # `onto` is @{upstream} or a full object name its upstream holds. Raises Blocked, or a
+        # subclass for git's own refusal, and the branch then stays where it was. Raises
+        # WriteTimeout when the deadline stops git partway through the checkout: the branch stays
+        # too, but the files git had written stay in the working tree.
+        def fast_forward(path, onto: UPSTREAM, reflog_action: REFLOG_ACTION)
+          unless onto == UPSTREAM || OBJECT_NAME.match?(onto)
+            raise ArgumentError, "onto must be #{UPSTREAM} or a full object name, not #{onto.inspect}"
+          end
+
+          directory = File.expand_path(path)
+          status = ready_status(directory)
+          from, to = revisions(directory, onto)
+          ahead, behind = position(directory, from, to)
+          return FastForward.new(from:, to: from, count: 0) if behind.zero?
+
+          target = onto == UPSTREAM ? status.upstream : to[0, Porcelain::ABBREVIATION]
+          raise Blocked.new(directory, 'Diverged', "#{ahead} ahead, #{behind} behind #{target}") if ahead.positive?
+
+          along_upstream(directory, to, status.upstream) unless onto == UPSTREAM
+          merge(directory, to, reflog_action)
+          FastForward.new(from:, to:, count: behind)
+        end
+
+        private
+
+        # `clean` refuses staged and unstaged changes; without it git alone decides whether the move
+        # would overwrite them.
+        def ready_status(directory, clean: true)
+          status = status(directory)
+          blocker = blocker(status, clean:)
+          raise Blocked.new(directory, *blocker) if blocker
+
+          locks = branch_locks(status.branch)
+          paths = git_paths(directory, *IN_PROGRESS.keys, SEQUENCER_TODO, *locks)
+          operation = operation(directory, paths.shift(IN_PROGRESS.size + 1))
+          raise Blocked.new(directory, 'InProgress', "#{operation} in progress") if operation
+
+          held = locks.zip(paths).find { |_, lock| File.exist?(lock) }&.first
+          raise Busy.new(directory, held) if held
+
+          status
+        end
+
+        # Git takes these when it updates the branch, after it has checked out the new tree and
+        # written the index, so one left behind would leave the tree moved and the branch not.
+        def branch_locks(branch) = ['HEAD.lock', "refs/heads/#{branch}.lock", 'reftable/tables.list.lock']
+
+        # In State.derive's order, so a blocking state is named as the STATUS column names it.
+        # Untracked files do not block: git refuses to overwrite one.
+        def blocker(status, clean:)
+          return ['Conflicted', unmerged(status.conflicted)] if status.conflicted.positive?
+          return ['Detached', "HEAD is detached at #{status.head}"] if status.detached?
+          return ['Unborn', 'no commits yet'] if status.unborn?
+          return ['Dirty', changes(status)] if clean && !(status.staged + status.unstaged).zero?
+
+          tracking(status)
+        end
+
+        def tracking(status)
+          return ['NoUpstream', "#{status.branch} tracks no upstream"] if status.upstream.nil?
+
+          ['Gone', "upstream #{status.upstream} no longer exists"] if status.upstream_gone?
+        end
+
+        def unmerged(count) = count == 1 ? '1 unmerged path' : "#{count} unmerged paths"
+
+        def changes(status) = "#{status.staged} staged, #{status.unstaged} unstaged"
+
+        # The merge names the commit the checks saw, not @{upstream}: a fetch running beside it
+        # could move the upstream in between, and the branch would then move further than checked.
+        def revisions(directory, onto)
+          missing = ->(failed) { onto != UPSTREAM && failed.err.include?(UNKNOWN_REVISION) }
+          result = run(directory, 'rev-parse', 'HEAD', "#{onto}^{commit}", accept: missing)
+          return result.out.split if result.success?
+
+          raise Blocked.new(directory, 'RevisionNotFound', "commit #{onto} is not in this repository")
+        end
+
+        def position(directory, from, to)
+          run(directory, 'rev-list', '--left-right', '--count', "#{from}...#{to}").out.split.map { Integer(it) }
+        end
+
+        # A commit the upstream lacks could come from any branch or fork the repository has
+        # fetched, so a named commit is reached only along the upstream.
+        def along_upstream(directory, commit, upstream)
+          return if upstream_holds?(directory, commit)
+
+          short = commit[0, Porcelain::ABBREVIATION]
+          raise Blocked.new(directory, 'OffUpstream', "commit #{short} is not on #{upstream}")
+        end
+
+        # merge-base --is-ancestor exits 1 without a word when the commit is not an ancestor.
+        def upstream_holds?(directory, commit)
+          lacks = ->(failed) { failed.status == 1 }
+          run(directory, 'merge-base', '--is-ancestor', commit, UPSTREAM, accept: lacks).success?
+        end
+
+        # A partial clone fetches the blobs a checkout needs, so the merge runs as a network command:
+        # no prompt, the allowed protocols only, and the network deadline. The deadline cannot tell
+        # that fetch from the write, and a smudge filter such as git-lfs's may contact a server too.
+        def merge(directory, commit, reflog_action)
+          result = run(directory, *Runner::NETWORK_CONFIG, *MERGE_ARGS, commit,
+                       accept: method(:refusal), network: true, timeout: @network_timeout,
+                       env: @network_environment.merge(REFLOG_VARIABLE => reflog_action))
+          raise refusal(result), directory unless result.success?
+        rescue Timeout
+          raise WriteTimeout.new(directory, seconds: @network_timeout)
+        end
+
+        def refusal(result) = REFUSALS.find { |pattern, _| pattern.match?(result.err) }&.last
+      end
+    end
+  end
+end

data/lib/slipway/git/fetch_result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # `updates` holds [ref, old, new] for each ref the fetch moved, or is nil when git fetched
+    # without listing them (git before 2.41). The old id of a new ref and the new id of a pruned
+    # one are git's all-zero id.
+    FetchResult = Data.define(:updates) do
+      # Parses `git fetch --porcelain`: one "FLAG OLD NEW REF" line per updated ref, and nothing
+      # when the fetch brought nothing new. A fetched ref that no refspec maps (a single-branch
+      # clone on a branch that tracks another one, a remote without a fetch refspec) is reported
+      # as FETCH_HEAD on every fetch, though no ref moved.
+      def self.parse(text)
+        updates = text.each_line(chomp: true).filter_map do |line|
+          old_id, new_id, ref = line[2..].split(' ', 3)
+          [ref, old_id, new_id].freeze unless ref == Repository::FETCH_HEAD
+        end
+        new(updates: updates.freeze)
+      end
+    end
+  end
+end

data/lib/slipway/git/move_back.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # `from` and `to` are the full object names the branch pointed at before and after the move,
+    # and `count` the commits it dropped: 0, with `to` equal to `from`, when the branch already
+    # stood at the target.
+    MoveBack = Data.define(:from, :to, :count) do
+      def moved? = to != from
+    end
+  end
+end

data/lib/slipway/git/reflog.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # One move of a branch as its reflog records it: the commit the branch pointed at after the
+    # move, when the move happened, and git's subject for it, such as "slipway sync: Fast-forward".
+    ReflogEntry = Data.define(:sha, :time, :subject)
+
+    module Reflog
+      # A date format makes %gd name the time of each move; %ct would be the commit's own date,
+      # the same for every move to one commit. log.showSignature would add gpg's lines.
+      FORMAT = ['--date=unix', '--format=%H%x00%gd%x00%gs', '--no-show-signature'].freeze
+      SELECTOR_TIME = /@\{(\d+)\}\z/
+      FIELDS = 3
+
+      # Parses `git reflog show -z` in FORMAT, newest entry first as git lists them.
+      def self.parse(text)
+        text.chomp("\0").split("\0", -1).each_slice(FIELDS).filter_map do |sha, selector, subject|
+          time = selector.to_s[SELECTOR_TIME, 1]
+          ReflogEntry.new(sha:, time: Time.at(Integer(time, 10)).utc, subject:) if time && subject
+        end
+      end
+    end
+  end
+end

data/lib/slipway/git/repository.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative 'fast_forwarding'
+require_relative 'reflog'
+require_relative 'rolling_back'
+require_relative 'runner'
+
+module Slipway
+  module Git
+    # Every git command slipway runs, asked of one registered path at a time. Each method runs
+    # git through the Runner, under the local deadline or, for #fetch and the moves, the network
+    # profile, and raises a Git::Error subclass when git fails: MissingPath, NotARepository,
+    # UnsafeRepository, NotInstalled or Timeout for the failures it names, a plain Error with
+    # git's first line for the rest. It keeps no state about a repository, so one instance
+    # serves every worker of a run; all it remembers is whether git predates
+    # `fetch --porcelain`.
+    class Repository
+      include FastForwarding
+      include RollingBack
+
+      STATUS_ARGS = %w[status --porcelain=v2 --branch --show-stash -z --untracked-files=normal --no-renames].freeze
+      # Six NUL separated fields in the order Commit.parse expects; -z terminates the record.
+      LOG_ARGS = ['log', '-1', '-z', '--format=%H%x00%h%x00%ct%x00%an%x00%ae%x00%s'].freeze
+      REMOTE_ARGS = %w[config --get remote.origin.url].freeze
+      # No remote argument: git fetches the remote of the current branch, else the only remote,
+      # else origin, as the user's own `git fetch` would, so nothing from a manifest reaches this
+      # argv. --no-all overrides fetch.all (git 2.44 and later), under which git would fetch every
+      # remote and --atomic would refuse to run.
+      FETCH_ARGS = %w[--no-all --atomic --no-recurse-submodules --no-auto-maintenance].freeze
+      # A branch that tracks another local branch has "." as its remote, and a remote-less fetch
+      # would read the repository itself: no remote-tracking ref moves, yet FETCH_HEAD is rewritten.
+      UPSTREAM_REMOTE_ARGS = ['for-each-ref', '--format=%(HEAD)%(upstream:remotename)', 'refs/heads/'].freeze
+      CURRENT_LOCAL_UPSTREAM = '*.'
+      # ls-remote without a remote picks one the way fetch does, and --get-url prints its URL
+      # without contacting it; with none to pick, git dies with this message, untranslated.
+      DEFAULT_REMOTE_ARGS = %w[ls-remote --get-url].freeze
+      NO_DEFAULT_REMOTE = 'No remote configured'
+      # Git learned `fetch --porcelain` in 2.41. An older git rejects the option as a usage error
+      # before it connects, and the fetch runs again without it.
+      PORCELAIN = '--porcelain'
+      PORCELAIN_UNKNOWN = /\Aerror: unknown option .porcelain'$/
+      USAGE_STATUS = 129
+      FETCH_HEAD = 'FETCH_HEAD'
+      COMMON_DIR_ARGS = %w[rev-parse --git-common-dir].freeze
+      # `git config --get` exits 1 when the key is absent, which is an answer, not a failure.
+      ABSENT_KEY_STATUS = 1
+      UNBORN_MESSAGE = 'does not have any commits yet'
+      MESSAGE_LIMIT = 200
+      NETWORK_TIMEOUT = 60
+      PROTOCOLS = %w[ssh https].freeze
+      PROTOCOLS_SOURCE = '"protocols" in the configuration file'
+      # What git and ssh print when credentials or a host key are missing, would need a prompt, or
+      # were refused by the remote.
+      AUTH_REQUIRED = Regexp.union('terminal prompts disabled', 'could not read Username', 'could not read Password',
+                                   'Authentication failed', 'Permission denied (publickey',
+                                   'Host key verification failed', 'returned error: 403')
+      # Git refuses a transport before it connects, so a real refusal is the whole of stderr and
+      # ends in die(). Over ssh the remote writes to the same stream, and a line it prints is
+      # followed by git's own message or ends in a signal (128 plus its number).
+      PROTOCOL_REFUSED = /\Afatal: transport '(?<protocol>[a-z][a-z0-9+.-]*)' not allowed\n\z/
+      DIE_STATUS = 128
+      # The paths git keeps in the git directory of a worktree while an operation waits for the
+      # user, in the order they are checked; the applying marker tells git am from a rebase. A
+      # rebase that stops on a merge also leaves MERGE_HEAD, and it is the rebase that must be
+      # continued or aborted.
+      IN_PROGRESS = { 'rebase-apply/applying' => 'git am session', 'rebase-apply' => 'rebase',
+                      'rebase-merge' => 'rebase', 'MERGE_HEAD' => 'merge', 'BISECT_LOG' => 'bisect' }.freeze
+      # The reftable backend keeps these in its ref store, where no path names them.
+      IN_PROGRESS_REFS = { 'CHERRY_PICK_HEAD' => 'cherry-pick', 'REVERT_HEAD' => 'revert' }.freeze
+      # A cherry-pick or revert of several commits is still under way after `git reset` drops its
+      # pseudoref, and git names it by the first command left in the sequencer's todo.
+      SEQUENCER_TODO = 'sequencer/todo'
+      SEQUENCER_COMMANDS = { 'pick' => 'cherry-pick', 'revert' => 'revert' }.freeze
+      LAZY_FETCH_VARIABLE = 'GIT_NO_LAZY_FETCH'
+      # A partial clone fetches an object it lacks from its remote, even for a read. --missing
+      # stops that on every supported git; GIT_NO_LAZY_FETCH, which git honors from 2.44, and an
+      # empty GIT_ALLOW_PROTOCOL, which refuses every transport before it connects, stand behind it.
+      OFFLINE_REV_LIST = %w[rev-list --missing=allow-any].freeze
+      REFLOG_ARGS = ['reflog', 'show', '-z', *Reflog::FORMAT].freeze
+      BAD_REVISION = 'bad revision'
+      OFFLINE_READ = { LAZY_FETCH_VARIABLE => '1', Runner::PROTOCOL_VARIABLE => '' }.freeze
+
+      def initialize(runner: Runner.new, network_timeout: NETWORK_TIMEOUT, protocols: PROTOCOLS,
+                     protocols_source: PROTOCOLS_SOURCE)
+        @runner = runner
+        @network_timeout = network_timeout
+        @network_environment = Runner.network_environment(protocols)
+        @protocols_source = protocols_source
+        # Cleared once git turns out to predate --porcelain; threads racing on it only repeat
+        # the rejected attempt.
+        @porcelain = true
+      end
+
+      def status(path)
+        Status.parse(run(path, *STATUS_ARGS).out)
+      end
+
+      def last_commit(path)
+        result = run(path, *LOG_ARGS, accept: method(:unborn?))
+        result.success? ? Commit.parse(result.out) : nil
+      end
+
+      def remote_url(path)
+        result = run(path, *REMOTE_ARGS, accept: ->(failed) { failed.status == ABSENT_KEY_STATUS })
+        result.success? ? result.out.chomp : nil
+      end
+
+      # Fetches from the remote git picks. Returns a FetchResult whose `updates` lists the refs
+      # that moved, empty when none did, or is nil when git predates 2.41 and cannot tell.
+      # Raises LocalUpstream, before anything is contacted, for a branch that tracks a local one,
+      # and AuthRequired, ProtocolNotAllowed, Timeout, NotInstalled or MissingPath when the fetch
+      # fails for those reasons.
+      def fetch(path, prune:)
+        raise LocalUpstream, File.expand_path(path) if local_upstream?(path)
+
+        options = [*FETCH_ARGS, *('--prune' if prune)]
+        if @porcelain
+          result = network_fetch(path, PORCELAIN, *options, accept: method(:porcelain_unknown?))
+          return FetchResult.parse(result.out) if result.success?
+
+          @porcelain = false
+        end
+        network_fetch(path, *options)
+        FetchResult.new(updates: nil)
+      end
+
+      def local_upstream?(path)
+        run(path, *UPSTREAM_REMOTE_ARGS).out.lines(chomp: true).include?(CURRENT_LOCAL_UPSTREAM)
+      end
+
+      def default_remote?(path)
+        run(path, *DEFAULT_REMOTE_ARGS, accept: method(:no_default_remote?)).success?
+      end
+
+      # The operation git is in the middle of in this worktree, such as "rebase", or nil.
+      def in_progress(path)
+        directory = File.expand_path(path)
+        operation(directory, git_paths(directory, *IN_PROGRESS.keys, SEQUENCER_TODO))
+      end
+
+      # How far HEAD is from `revision`, a full object name, or nil when the repository holds no
+      # commit by that name. `tracking` says the branch has an upstream that exists, and a HEAD
+      # behind the revision then also learns how many of its commits the upstream lacks.
+      def distance(path, revision, tracking: false)
+        unless OBJECT_NAME.match?(revision)
+          raise ArgumentError, "revision must be a full object name, not #{revision.inspect}"
+        end
+
+        ahead, behind = offline_count(path, "HEAD...#{revision}^{commit}", '--left-right')
+        return if ahead.nil?
+
+        counted = tracking && ahead.zero? && behind.positive?
+        off_upstream = offline_count(path, "#{UPSTREAM}..#{revision}^{commit}").first if counted
+        Distance.new(ahead:, behind:, off_upstream:)
+      end
+
+      # The moves git logged for `branch`, newest first. Git answers "bad revision" for a branch
+      # without commits, and logs nothing under core.logAllRefUpdates=false unless a log exists.
+      def reflog(path, branch)
+        result = run(path, *REFLOG_ARGS, "refs/heads/#{branch}", '--',
+                     accept: ->(failed) { failed.err.include?(BAD_REVISION) })
+        result.success? ? Reflog.parse(result.out) : []
+      end
+
+      # How many commits `to` reaches that `from` does not, both full object names, or nil when the
+      # repository lacks either.
+      def commits_between(path, from, to)
+        [from, to].each do |name|
+          raise ArgumentError, "expected a full object name, not #{name.inspect}" unless OBJECT_NAME.match?(name)
+        end
+        offline_count(path, "#{from}^{commit}..#{to}^{commit}").first
+      end
+
+      # nil for a repository that was never fetched or whose last fetch failed: git empties
+      # FETCH_HEAD before it contacts the remote and writes a line for each ref it fetched.
+      # Every worktree shares the remote-tracking refs, but git writes FETCH_HEAD in the worktree
+      # that ran the fetch, so the newest one dates them.
+      def fetched_at(path)
+        head = fetch_heads(File.expand_path(path)).filter_map { File.stat(it) if File.file?(it) }.max_by(&:mtime)
+        head.mtime.utc if head && !head.zero?
+      end
+
+      # Symlinks are resolved, so projects on one repository name the same directory however
+      # their paths are written. A .git directory is read without a spawn, so listing projects
+      # costs no extra git process.
+      def common_dir(path)
+        directory = File.expand_path(path)
+        git_dir = File.join(directory, '.git')
+        return File.realpath(git_dir) if File.directory?(git_dir)
+
+        File.realpath(run(directory, *COMMON_DIR_ARGS).out.chomp, directory)
+      end
+
+      private
+
+      # The spawn is skipped for a path that is not a directory, since git would only say the same.
+      def run(path, *, accept: nil, network: false, **)
+        directory = File.expand_path(path)
+        raise MissingPath, directory unless File.directory?(directory)
+
+        result = @runner.run(directory, *, **)
+        return result if result.success? || accept&.call(result)
+
+        raise classify(directory, result, network:)
+      end
+
+      # The counts rev-list prints for `range`, or none when it names an object the repository lacks.
+      def offline_count(path, range, *options)
+        result = run(path, *OFFLINE_REV_LIST, *options, '--count', range,
+                     accept: ->(failed) { failed.err.include?(UNKNOWN_REVISION) }, env: OFFLINE_READ)
+        result.success? ? result.out.split.map { Integer(it) } : []
+      end
+
+      def network_fetch(path, *, accept: nil)
+        run(path, *Runner::NETWORK_CONFIG, 'fetch', *, accept:, network: true,
+                                                       timeout: @network_timeout, env: @network_environment)
+      end
+
+      # base: keeps glob metacharacters in the repository path literal.
+      def fetch_heads(directory)
+        common = common_dir(directory)
+        worktrees = File.join(common, 'worktrees')
+        [File.join(common, FETCH_HEAD), *Dir.glob("*/#{FETCH_HEAD}", base: worktrees).map { File.join(worktrees, it) }]
+      end
+
+      def git_paths(directory, *names)
+        paths = run(directory, 'rev-parse', *names.flat_map { ['--git-path', it] }).out.lines(chomp: true)
+        paths.map { File.expand_path(it, directory) }
+      end
+
+      # `paths` holds the path of each IN_PROGRESS marker, then of the sequencer's todo.
+      def operation(directory, paths)
+        *markers, todo = paths
+        IN_PROGRESS.values.zip(markers).find { |_, marker| File.exist?(marker) }&.first ||
+          IN_PROGRESS_REFS.find { |ref, _| ref?(directory, ref) }&.last ||
+          sequence(todo)
+      end
+
+      # rev-parse -q --verify exits 1 without a word for a ref that does not exist.
+      def ref?(directory, ref)
+        run(directory, 'rev-parse', '-q', '--verify', ref, accept: ->(failed) { failed.status == 1 }).success?
+      end
+
+      # The todo holds commit subjects, which need not be UTF-8.
+      def sequence(todo)
+        SEQUENCER_COMMANDS.fetch(File.binread(todo)[/\S+/], 'cherry-pick')
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        nil
+      end
+
+      def unborn?(result) = result.err.include?(UNBORN_MESSAGE)
+
+      def porcelain_unknown?(result) = result.status == USAGE_STATUS && PORCELAIN_UNKNOWN.match?(result.err)
+
+      def no_default_remote?(result) = result.status == DIE_STATUS && result.err.include?(NO_DEFAULT_REMOTE)
+
+      def classify(path, result, network:)
+        failure = network ? network_failure(path, result) : local_failure(path, result)
+        failure || Error.new(path, "git exited with status #{result.status}: #{first_line(result.err)}")
+      end
+
+      # Git's stderr under LC_ALL=C opens with a stable phrase for each local failure Slipway
+      # names. A network command's stderr may open with what ssh or the remote printed, so these
+      # phrases describe the local repository only for a command that never leaves the machine.
+      def local_failure(path, result)
+        case result.err
+        when /\Afatal: not a git repository/ then NotARepository.new(path)
+        when /\Afatal: cannot change to/ then MissingPath.new(path)
+        when /\Afatal: detected dubious ownership/ then UnsafeRepository.new(path)
+        end
+      end
+
+      def network_failure(path, result)
+        refusal = PROTOCOL_REFUSED.match(result.err) if result.status == DIE_STATUS
+        return ProtocolNotAllowed.new(path, protocol: refusal[:protocol], source: @protocols_source) if refusal
+
+        refused = result.err.each_line.find { AUTH_REQUIRED.match?(it) }
+        AuthRequired.new(path, redacted(refused)) if refused
+      end
+
+      def first_line(err) = redacted(err.lines.first)
+
+      # Git quotes the URL it failed on, credentials included, and a server can add lines of its
+      # own. Redacting before the cut keeps a password from surviving as a truncated URL.
+      def redacted(line) = Url.redact(line.to_s.strip)[0, MESSAGE_LIMIT]
+    end
+  end
+end

data/lib/slipway/git/rolling_back.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'move_back'
+
+module Slipway
+  module Git
+    class Repository
+      # The one reset slipway runs, and the checks around it. It shares the fast-forward's checks
+      # of the repository's state, but lets unstaged changes through: reset --keep keeps an
+      # unstaged change to a file the move leaves alone and refuses one to a file it rewrites.
+      # It resets every index entry, though, so a staged change would be lost and is refused.
+      module RollingBack
+        ROLLBACK_ACTION = 'slipway rollout undo'
+        RESET_ARGS = %w[reset --keep --quiet --no-recurse-submodules].freeze
+        # Literal, so a name git would read as pathspec magic stays a name; icase, because on a
+        # case-insensitive file system the file in the way may differ in case.
+        LITERAL = ':(literal,icase)'
+
+        # Moves the checked-out branch back to `to`, a full object name of a commit HEAD contains,
+        # only when @{upstream} holds every commit the move drops. Raises Blocked, or a subclass for
+        # git's own refusal, and the branch then stays where it was, or WriteTimeout as the
+        # fast-forward does.
+        def roll_back(path, to:, reflog_action: ROLLBACK_ACTION)
+          unless FastForwarding::OBJECT_NAME.match?(to)
+            raise ArgumentError, "to must be a full object name, not #{to.inspect}"
+          end
+
+          directory = File.expand_path(path)
+          status = ready_status(directory, clean: false)
+          raise Blocked.new(directory, 'Dirty', changes(status)) if status.staged.positive?
+
+          from, to = revisions(directory, to)
+          dropped, gained = position(directory, from, to)
+          return MoveBack.new(from:, to: from, count: 0) if (dropped + gained).zero?
+
+          behind_head(directory, status, to, gained)
+          kept_upstream(directory, status, from)
+          clear_way(directory, from, to)
+          reset(directory, to, reflog_action)
+          MoveBack.new(from:, to:, count: dropped)
+        end
+
+        private
+
+        def behind_head(directory, status, commit, gained)
+          return if gained.zero?
+
+          short = commit[0, Porcelain::ABBREVIATION]
+          raise Blocked.new(directory, 'Diverged', "commit #{short} is not on the history of #{status.branch}")
+        end
+
+        # Every commit the move drops stays reachable from the upstream, so none of them exists only
+        # in this repository.
+        def kept_upstream(directory, status, head)
+          return if upstream_holds?(directory, head)
+
+          raise Blocked.new(directory, 'LocalCommits',
+                            "#{status.branch} has commits that are not on #{status.upstream}")
+        end
+
+        # reset --keep refuses to overwrite an untracked file but replaces an ignored one, whose
+        # content was never committed, so the paths the move adds are checked for either first.
+        def clear_way(directory, from, to)
+          added = run(directory, 'diff', '--name-only', '-z', '--no-renames', '--diff-filter=A', from, to, '--')
+          suspects = added.out.split("\0").flat_map { in_the_way(directory, it) }.uniq
+          return if suspects.empty?
+
+          others = run(directory, 'ls-files', '-z', '--others', '--', *suspects.map { LITERAL + it })
+          raise WouldOverwrite, directory unless others.out.empty?
+        end
+
+        # The entries on disk git would have to replace to write `path`: the path itself, and any
+        # parent directory that is a file or a symbolic link instead. ls-files then tells whether
+        # git tracks them.
+        def in_the_way(directory, path)
+          parts = path.split('/')
+          parents = (1...parts.size).map { parts.first(it).join('/') }
+          [*parents.reject { real_directory?(File.join(directory, it)) }, path].select do |entry|
+            File.symlink?(File.join(directory, entry)) || File.exist?(File.join(directory, entry))
+          end
+        end
+
+        def real_directory?(path) = File.directory?(path) && !File.symlink?(path)
+
+        # A partial clone fetches the blobs the reset writes, so it runs as the merge does.
+        def reset(directory, commit, reflog_action)
+          result = run(directory, *Runner::NETWORK_CONFIG, *RESET_ARGS, commit, '--',
+                       accept: method(:refusal), network: true, timeout: @network_timeout,
+                       env: @network_environment.merge(FastForwarding::REFLOG_VARIABLE => reflog_action))
+          raise refusal(result), directory unless result.success?
+        rescue Timeout
+          raise WriteTimeout.new(directory, seconds: @network_timeout)
+        end
+      end
+    end
+  end
+end