slipway 0.1.0

data/lib/slipway/commands/get.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../views'
+
+module Slipway
+  module Commands
+    class Get < Base
+      DESCRIPTION = "Display one or many resources.\n\n" \
+                    'Prints a table of the most important information about the specified resources. ' \
+                    'You can filter the list using a label selector and the --selector flag, or a field ' \
+                    'selector and the --field-selector flag. Projects are listed in the current group unless ' \
+                    "you pass --all-groups.\n\n" \
+                    'Use -o wide to add the path, the head commit, the age of the last commit and the drift of ' \
+                    'each project: the ways its repository differs from its manifest and what keeps sync from ' \
+                    "converging it. Use -o json or -o yaml for the full object with its status.\n\n" \
+                    "#{Options::TYPES_SENTENCE}".freeze
+      USAGE = '(TYPE [NAME...] | TYPE/NAME...)'
+      COLUMNS = {
+        'GROUP' => 'The group of the project.',
+        'NAME' => 'The name of the resource.',
+        'BRANCH' => "The checked-out branch, or #{Views::Project::DETACHED} when HEAD points at a commit.",
+        'STATUS' => 'One word for the state of the repository, from the list below.',
+        'FETCHED' => 'Time since the repository was last fetched, by slipway or by git itself and from any of its ' \
+                     "worktrees. #{Views::Project::NEVER} means git answered and no fetch is on record, which " \
+                     'includes a last fetch that failed.',
+        'AGE' => 'Time since the resource was registered, in kubectl\'s units (3s, 4m12s, 11h, 2y319d).',
+        'PATH' => 'The registered path, as the manifest writes it.',
+        'HEAD' => 'The abbreviated id of the checked-out commit.',
+        'LAST-COMMIT' => 'The age of the checked-out commit.',
+        'DRIFT' => 'The ways the repository differs from its manifest and the blocker that keeps sync from ' \
+                   'fast-forwarding it, as slipway diff names them.',
+        'PROJECTS' => 'The number of projects in the group.',
+        'DESCRIPTION' => 'The description of the group.',
+        'LABELS' => 'The labels, as key=value pairs.'
+      }.freeze
+      STATUS_WORDS = CLI::Glossary.new(title: 'Status Words',
+                                       intro: 'STATUS is the first of these words that holds, in this order.',
+                                       entries: State::MEANINGS)
+      GLOSSARIES = [
+        CLI::Glossary.new(
+          title: 'Columns',
+          intro: 'Projects show NAME, BRANCH, STATUS, FETCHED and AGE; --all-groups adds GROUP in front, -o wide ' \
+                 'adds PATH, HEAD, LAST-COMMIT and DRIFT, and --show-labels adds LABELS. Groups show NAME, ' \
+                 'PROJECTS and AGE, and -o wide adds DESCRIPTION. A cell slipway has no value for reads ' \
+                 "#{Output::Table::NONE}, as every cell from git does when git cannot read the repository.",
+          entries: COLUMNS
+        ),
+        STATUS_WORDS
+      ].freeze
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'get', summary: 'Display one or many resources', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE, glossaries: GLOSSARIES,
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: true, required: false)],
+          options: [Options::OUTPUT, Options::SELECTOR, Options::FIELD_SELECTOR, Options::ALL_GROUPS,
+                    Options::NO_HEADERS, Options::SHOW_LABELS],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'List all projects in the current group', command: 'get projects'),
+          CLI::Example.new(comment: 'List all projects in every group, with the path and last commit',
+                           command: 'get projects -A -o wide'),
+          CLI::Example.new(comment: 'List a single project in YAML output format',
+                           command: 'get project hldr -o yaml'),
+          CLI::Example.new(comment: 'List the projects labeled lang=rust', command: 'get projects -l lang=rust'),
+          CLI::Example.new(comment: 'List the projects in every group that are not clean',
+                           command: 'get projects -A --field-selector status.state!=Clean'),
+          CLI::Example.new(comment: 'List the projects no fetch has reached',
+                           command: 'get projects --field-selector status.lastFetch=never'),
+          CLI::Example.new(comment: 'List every group', command: 'get groups')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, names = scope.targets(args)
+        fields = scope.field_selector(kind, names)
+        scope.select(kind, names) do |resources|
+          printer = Printer.new(runtime, context, opts, group_column: scope.all_groups?)
+          items = printer.items(kind, resources, fields)
+          next scope.report_none(kind) if items.empty?
+
+          printer.print(kind, items, single: names.size == 1)
+        end
+      end
+
+      class Printer
+        def initialize(runtime, context, opts, group_column:)
+          @runtime = runtime
+          @context = context
+          @opts = opts
+          @group_column = group_column
+        end
+
+        # Projects come back examined for every format but name, the one that shows nothing
+        # git answers. A field selector reads what git answered, so with one even -o name
+        # examines them.
+        def items(kind, resources, fields)
+          return fields.filter(resources) { group_object(it) } unless kind.namespaced?
+          return resources if name? && fields.empty?
+
+          inspections = fields.filter(examine(resources)) { Views::Project.object(it) }
+          name? ? inspections.map(&:project) : inspections
+        end
+
+        def print(kind, items, single:)
+          case @opts[:output]
+          when Output::NAME then items.each { @context.puts("#{kind.singular}/#{it.name}") }
+          when *Output::Serializer::STRUCTURED then objects(kind, items, single:)
+          else table(kind, items)
+          end
+        end
+
+        private
+
+        def objects(kind, items, single:)
+          objects = items.map { kind.namespaced? ? Views::Project.object(it) : group_object(it) }
+          @context.print(Output::Serializer.render(@opts[:output], objects, single:))
+        end
+
+        def table(kind, items)
+          headers, rows, roles, offset = kind.namespaced? ? project_table(items) : group_table(items)
+          Output::Table.new(@context, headers:, show_headers: !@opts[:no_headers], roles:, color_offset: offset)
+                       .print(rows)
+        end
+
+        # The GROUP column -A prepends is left out of the color cycle, so the other columns
+        # keep the colors they have without -A.
+        def project_table(inspections)
+          columns = { wide: wide?, group: @group_column, labels: labels? }
+          now = @runtime.clock.call
+          [Views::Project.headers(**columns), inspections.map { Views::Project.row(it, now:, **columns) },
+           Views::Project::ROLES, @group_column ? 1 : 0]
+        end
+
+        def group_table(groups)
+          columns = { wide: wide?, labels: labels? }
+          now = @runtime.clock.call
+          [Views::Group.headers(**columns), groups.map { Views::Group.row(it, count: count(it), now:, **columns) },
+           nil, 0]
+        end
+
+        def examine(resources) = Base.examine(@runtime, @context, resources)
+
+        def group_object(group) = Views::Group.object(group, count: count(group))
+
+        def count(group) = @runtime.store.project_count(group.name)
+
+        def wide? = @opts[:output] == Output::WIDE
+
+        def labels? = @opts[:show_labels] == true
+
+        def name? = @opts[:output] == Output::NAME
+      end
+
+      private_constant :Printer
+    end
+  end
+end

data/lib/slipway/commands/label.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../labels'
+
+module Slipway
+  module Commands
+    class Label < Base
+      DESCRIPTION = <<~TEXT.chomp
+        Update the labels on a resource.
+
+          *  A label key and value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores, up to 63 characters each.
+          *  Optionally, the key can begin with a DNS subdomain prefix and a single '/', like example.com/my-app.
+          *  If --overwrite is true, then existing labels can be overwritten, otherwise attempting to overwrite a label will result in an error.
+          *  KEY- removes the label KEY; removing a label that is not set changes nothing. A change that leaves the labels as they were prints not labeled.
+
+        #{Options::TYPES_SENTENCE}
+      TEXT
+      NO_CHANGES = 'at least one label update is required'
+      LABELED = 'labeled'
+      UNLABELED = 'unlabeled'
+      NOT_LABELED = 'not labeled'
+
+      OVERWRITE = CLI::Option.new(long: 'overwrite',
+                                  description: 'If true, allow labels to be overwritten, otherwise reject label ' \
+                                               'updates that overwrite existing labels.')
+      LIST = CLI::Option.new(long: 'list',
+                             description: 'If true, display the labels for a given resource instead of writing them.')
+      CHANGE = CLI::Positional.new(name: 'KEY=VALUE|KEY-', required: false, variadic: true)
+      USAGE = "(TYPE NAME | TYPE/NAME) #{CHANGE.usage}".freeze
+
+      Change = Data.define(:sets, :removals) do
+        # A malformed, repeated or contradictory word is a usage error.
+        def self.parse(words) = new(*Labels.parse_changes(words))
+
+        def empty? = sets.empty? && removals.empty?
+
+        # Refuses a silent overwrite with kubectl's error message.
+        def apply(labels, overwrite:)
+          sets.each do |key, value|
+            next if overwrite || !labels.key?(key) || labels[key] == value
+
+            raise Error, "'#{key}' already has a value (#{labels[key]}), and --overwrite is false"
+          end
+          labels.merge(sets).except(*removals)
+        end
+
+        def outcome(labels)
+          return [LABELED, :label_labeled] if sets.any? { |key, value| labels[key] != value }
+          return [UNLABELED, :label_unlabeled] if removals.any? { labels.key?(it) }
+
+          [NOT_LABELED, :label_not_labeled]
+        end
+      end
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'label', summary: 'Update the labels on a resource', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE,
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: false, required: false), CHANGE],
+          options: [OVERWRITE, LIST, Options::DRY_RUN],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: "Update project 'hldr' with the label 'lang' and the value 'rust'",
+                           command: 'label project hldr lang=rust'),
+          CLI::Example.new(comment: "Update project 'hldr' with the label 'lang' and the value 'go', overwriting " \
+                                    'any existing value', command: 'label project hldr lang=go --overwrite'),
+          CLI::Example.new(comment: "Remove the label 'tier' from project 'hldr'", command: 'label project hldr tier-'),
+          CLI::Example.new(comment: "List the labels of group 'work'", command: 'label group work --list')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, name, words = split(scope, args)
+        change = Change.parse(words)
+        raise CLI::UsageError, NO_CHANGES if change.empty? && opts[:list] != true
+
+        resource = runtime.store.find(kind, name, group: kind.namespaced? ? scope.group : nil)
+        labels = change.apply(resource.labels, overwrite: opts[:overwrite] == true)
+        return list(context, labels) if opts[:list] == true
+
+        write(runtime.store, context, kind, resource.with_labels(labels), change.outcome(resource.labels),
+              dry_run: opts[:dry_run] == true)
+      end
+
+      private
+
+      def split(scope, args)
+        type, *rest = args
+        return [*scope.target([type]), rest] if type.include?('/')
+
+        [*scope.target([type, *rest.first(1)]), rest.drop(1)]
+      end
+
+      def write(store, context, kind, resource, (word, role), dry_run:)
+        store.save(resource) unless dry_run || word == NOT_LABELED
+        result_line(context, kind, resource.name, word, role, dry_run:)
+      end
+
+      # `--list` computes the labels without writing them, as kubectl does.
+      def list(context, labels)
+        labels.sort.each { |key, value| context.puts("#{key}=#{value}") }
+      end
+    end
+  end
+end

data/lib/slipway/commands/manual.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../settings'
+require_relative '../git'
+
+module Slipway
+  module Commands
+    # The parts of slipway(1) that belong to no single verb. CLI::Manpage renders them, and
+    # bin/generate-man hands them over, because the files and variables they name are slipway's.
+    module Manual
+      EXIT_STATUSES = {
+        '0' => 'Success.',
+        '1' => 'Runtime error, such as a missing resource or an unreadable manifest.',
+        '2' => 'Usage error: unknown command, unknown flag or invalid argument.',
+        '130' => 'Interrupted by SIGINT.'
+      }.freeze
+      # A setting's variable points at the CONFIGURATION entry that describes its value, so the
+      # value is described once.
+      def self.setting(key, rest = '')
+        variable = Settings::ALL.find { it.key == key }.variable
+        [variable, "Outranks the #{key} key (see CONFIGURATION)#{rest}."]
+      end
+      private_class_method :setting
+
+      # Every variable the code reads but HOME and PATH, which test/unit/seams_test.rb checks.
+      ENVIRONMENT = {
+        'SLIPWAY_CONFIG' => 'Path of the configuration file; overridden by --config.',
+        'SLIPWAY_DATA_HOME' => 'Directory holding the registry: group and project manifests.',
+        **[setting('color', '; --color outranks both'), setting('theme'), setting('editor', ', VISUAL and EDITOR'),
+           setting('group', '; --group outranks both'), setting('networkTimeout'), setting('parallel'),
+           setting('protocols', '; the names are separated by colons, as in ssh:https')].to_h,
+        'SLIPWAY_DEBUG' => 'When non-empty, unexpected errors also print their class and backtrace.',
+        'NO_COLOR' => 'When non-empty, disables color in auto mode.',
+        'FORCE_COLOR' => 'When non-empty, enables color in auto mode even without a terminal.',
+        'CLICOLOR_FORCE' => 'Same as FORCE_COLOR.',
+        'VISUAL' => 'Editor used by edit when SLIPWAY_EDITOR and the editor configuration key are unset.',
+        'EDITOR' => 'Editor used by edit when VISUAL is unset as well.',
+        'XDG_CONFIG_HOME' => 'Base of the configuration directory (default ~/.config).',
+        'XDG_DATA_HOME' => 'Base of the data directory (default ~/.local/share).',
+        'TERM' => 'When dumb, disables color in auto mode.',
+        'MANPAGER' => 'When non-empty, slipway man leaves the pager palette alone.',
+        'MANROFFOPT' => 'Same as MANPAGER.',
+        'LESS_TERMCAP_md' => 'Same as MANPAGER.',
+        'GROFF_NO_SGR' => 'Same as MANPAGER.'
+      }.freeze
+      # The variables slipway clears for git instead of reading them.
+      CLEARED = {
+        Git::Runner::ENVIRONMENT.filter_map { |name, value| name if value.nil? && name.start_with?('GIT_') }
+                                .join(', ') =>
+          'Ignored: every git command slipway runs starts without them, so an inherited value cannot point git at ' \
+          'another repository.'
+      }.freeze
+      FILES = {
+        '$XDG_CONFIG_HOME/slipway/config.yaml' =>
+          'Configuration file; see CONFIGURATION. Also set by --config or SLIPWAY_CONFIG.',
+        '$XDG_DATA_HOME/slipway/' =>
+          'Registry data: groups/NAME.yaml and projects/GROUP/NAME.yaml. Also set by SLIPWAY_DATA_HOME.'
+      }.freeze
+
+      # The keyword arguments CLI::Manpage takes for slipway's own sections.
+      def self.sections
+        { environment: ENVIRONMENT.merge(CLEARED), files: FILES, configuration: Settings::DOCUMENTATION,
+          exit_statuses: EXIT_STATUSES }
+      end
+    end
+  end
+end

data/lib/slipway/commands/options.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../cli'
+require_relative '../resources'
+require_relative '../output'
+require_relative '../views'
+
+module Slipway
+  module Commands
+    module Options
+      OUTPUT = CLI::Option.new(long: 'output', short: 'o', argument: 'FORMAT', enum: Output::FORMATS,
+                               default: Output::TABLE, description: 'Output format.')
+      SELECTOR = CLI::Option.new(long: 'selector', short: 'l', argument: 'EXPR',
+                                 description: "Selector (label query) to filter on, supports '=', '==', '!=', 'in', " \
+                                              "'notin' (e.g. -l key1=value1,key2=value2,key3 in (value3)). " \
+                                              'Matching objects must satisfy all of the specified label constraints.')
+      FIELD_SELECTOR = CLI::Option.new(long: 'field-selector', argument: 'EXPR',
+                                       description: "Selector (field query) to filter on, supports '=', '==', and " \
+                                                    "'!=' (e.g. --field-selector key1=value1,key2=value2). Projects " \
+                                                    "support #{Views::Project::FIELDS.keys.join(', ')}; groups " \
+                                                    "support #{Views::Group::FIELDS.keys.join(', ')}. Values " \
+                                                    'compare exactly, case included, with the object -o json ' \
+                                                    'prints: spec.path as registered, status.lastFetch as an RFC ' \
+                                                    '3339 time. A field the object leaves out compares as the ' \
+                                                    'empty value, except status.lastFetch, which compares as never. ' \
+                                                    'A backslash escapes a backslash, a comma or an equals sign in ' \
+                                                    'a value.')
+      ALL_GROUPS = CLI::Option.new(long: 'all-groups', short: 'A',
+                                   description: 'If present, list the requested object(s) across all groups. ' \
+                                                'The group in the current configuration is ignored even if ' \
+                                                'specified with --group.')
+      NO_HEADERS = CLI::Option.new(long: 'no-headers',
+                                   description: "When using the default output format, don't print headers.")
+      SHOW_LABELS = CLI::Option.new(long: 'show-labels',
+                                    description: 'When printing, show all labels as the last column.')
+      DRY_RUN = CLI::Option.new(long: 'dry-run', description: 'Print what would change and write nothing.')
+
+      TYPE_DESCRIPTIONS = {
+        'projects' => 'Registered git repositories',
+        'groups' => 'Namespaces that hold projects'
+      }.freeze
+
+      TYPES = Resources::KINDS.map { "#{it.plural} (#{[it.singular, *it.aliases].join(', ')})" }.join(' and ')
+      TYPES_SENTENCE = "Resource types: #{TYPES}. Type words are case-insensitive.".freeze
+
+      # Unknown words are reported by Resources.resolve at run time.
+      TYPE = CLI::Positional.new(name: 'TYPE', completer: ->(_given, _current) { TYPE_DESCRIPTIONS })
+
+      def self.name_positional(factory, variadic: true, required: false)
+        CLI::Positional.new(name: 'NAME', variadic:, required:,
+                            completer: ->(given, _current) { names(factory, given) })
+      end
+
+      # No TYPE word comes first, so completion always offers project names.
+      def self.project_positional(factory, variadic: true, required: false)
+        CLI::Positional.new(name: 'NAME', variadic:, required:,
+                            completer: ->(_given, _current) { names(factory, [Resources::PROJECTS.plural]) })
+      end
+
+      def self.group_completer(factory) = ->(_given, _current) { names(factory, [Resources::GROUPS.plural]) }
+
+      # Runs during shell completion, with the process environment and no flags: any failure
+      # means no candidates rather than an error in the shell.
+      def self.names(factory, given)
+        runtime = factory.call(CLI::Context.system, {})
+        runtime.store.names(Resources.resolve(given.fetch(0)), group: nil)
+      rescue StandardError
+        []
+      end
+      private_class_method :names
+    end
+  end
+end

data/lib/slipway/commands/results.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../git'
+require_relative '../output'
+require_relative '../pool'
+
+module Slipway
+  module Commands
+    # The lines of a verb that acts on each selected repository: one result per project, its
+    # details below it, and a count of the results on stderr once more than one project ran.
+    class Results
+      INDENT = '  '
+      DRY_RUN = '(dry run)'
+
+      # `roles` maps each result word to its theme role, in the order the count lists them.
+      def initialize(context, roles, dry_run:)
+        @context = context
+        @roles = roles
+        @dry_run = dry_run
+        @tally = Hash.new(0)
+      end
+
+      # Runs `work` for each project on a pool of `workers` and prints each outcome, or what the
+      # block turns it into on the calling thread, in the order the projects are listed.
+      # Ruby buffers a stdout that is not a terminal: a pipe would see the lines only at exit,
+      # after the count on stderr, and since Ruby flushes stdout before it spawns, a line a
+      # closed pipe refused would stay in the buffer and fail every later git with EPIPE.
+      def stream(projects, workers:, work:)
+        @context.unbuffer
+        Pool.new(workers:).each_ordered(projects, work) { report(block_given? ? yield(it) : it) }
+      end
+
+      def any?(*words) = words.any? { @tally.key?(it) }
+
+      def summarize
+        count = @tally.values.sum
+        return if count < 2
+
+        counts = @roles.keys.filter_map { "#{@tally[it]} #{it}" if @tally.key?(it) }
+        line = "#{count} projects: #{counts.join(', ')}"
+        line += " #{DRY_RUN}" if @dry_run
+        @context.warn(@context.paint_err(:muted, line))
+      end
+
+      # Ref names and messages come from git and the remote, so they are redacted and made plain.
+      def report(outcome)
+        word = outcome.word
+        @tally[word] += 1
+        line = Base.result_text(@context, Resources::PROJECTS, outcome.project.name, word, @roles.fetch(word),
+                                reason: outcome.reason, dry_run: @dry_run)
+        details = outcome.details.map { INDENT + @context.paint(:muted, Output.plain(Git::Url.redact(it))) }
+        @context.puts(line, *details)
+      end
+    end
+  end
+end

data/lib/slipway/commands/rollout.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'rollout_undo'
+require_relative 'rollout_spec'
+require_relative '../paths'
+require_relative '../rollout_history'
+
+module Slipway
+  module Commands
+    module Rollout
+      DESCRIPTION = "Manage the rollout of a project.\n\n" \
+                    'Slipway records a revision each time it moves the checked-out branch of a project: every ' \
+                    'fast-forward of slipway sync and every slipway rollout undo leaves an entry in the ' \
+                    "branch's reflog, and the commit the branch stood at before such a move is a revision too. " \
+                    'rollout history lists the revisions, rollout undo returns the branch to one of them and ' \
+                    'holds the project there with spec.revision, and rollout unpin lets sync follow the upstream ' \
+                    'again. rollout pause keeps fetch and sync away from a project until rollout resume.'
+      SINGLE_USAGE = '(NAME | project/NAME)'
+      MANY_USAGE = '(NAME... | project/NAME...)'
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'rollout', summary: 'Manage the rollout of a project', section: 'Repository Commands',
+          description: DESCRIPTION,
+          subcommands: [History, Undo, Unpin, Pause, Resume].map { it.command(factory) }
+        )
+      end
+
+      class History < Base
+        DESCRIPTION = "View the rollout history of a project.\n\n" \
+                      'Lists the revisions of the checked-out branch, oldest first: each commit slipway moved the ' \
+                      'branch to, read from the entries of the branch\'s reflog whose subject starts with ' \
+                      '"slipway ", and the commit the branch stood at before such a move. REVISION numbers them ' \
+                      'from the oldest entry git still keeps, COMMIT is the commit, DATE the time the branch ' \
+                      'moved there, CHANGE-CAUSE the move slipway made, and PINNED marks the revision spec.revision ' \
+                      "holds the project at. Nothing is fetched or written.\n\n" \
+                      'The history lasts as long as git keeps the reflog (gc.reflogExpire, 90 days by default; ' \
+                      'slipway never runs gc), and git keeps none under core.logAllRefUpdates=false. A project ' \
+                      'without history prints a notice on stderr and exits with status 0.'
+        HEADERS = %w[REVISION COMMIT DATE CHANGE-CAUSE PINNED].freeze
+        EMPTY = 'No rollout history found for %s.'
+        DETACHED = '%s: HEAD is detached at %s; rollout history reads the reflog of the checked-out branch'
+        ABBREV = Git::Porcelain::ABBREVIATION
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'history', summary: 'View rollout history', description: DESCRIPTION, usage: SINGLE_USAGE,
+            examples: [
+              CLI::Example.new(comment: 'View the rollout history of project hldr', command: 'rollout history hldr'),
+              CLI::Example.new(comment: 'View the rollout history of project api in the work group',
+                               command: 'rollout history project/api -n work')
+            ],
+            positionals: [Options.project_positional(factory, variadic: false, required: true)],
+            handler: new(factory)
+          )
+        end
+
+        def kinds = [Resources::PROJECTS]
+
+        def run(runtime, context, args, opts)
+          scope = scope(runtime, context, opts)
+          names = scope.project_targets(args, verb: 'view the rollout history of')
+          scope.select(Resources::PROJECTS, names) { |projects| projects.each { show(runtime, context, it) } }
+        end
+
+        private
+
+        def show(runtime, context, project)
+          name = "#{Resources::PROJECTS.singular}/#{project.name}"
+          path = Paths.expand(project.path, home: runtime.paths.home)
+          history = RolloutHistory.new(entries(runtime, project, name, path))
+          return context.warn(context.paint_err(:muted, format(EMPTY, name))) if history.empty?
+
+          pinned = history.pinned(project.revision)
+          rows = history.revisions.map { row(runtime, path, history, it, pinned) }
+          Output::Table.new(context, headers: HEADERS).print(rows)
+        end
+
+        def row(runtime, path, history, revision, pinned)
+          [revision.number, revision.sha[0, ABBREV], Resources.timestamp(revision.time),
+           cause(runtime, path, history, revision), revision.equal?(pinned)]
+        end
+
+        # A branch without commits has no reflog yet, and so no history.
+        def entries(runtime, project, name, path)
+          inspection = runtime.inspector.examine(project)
+          raise inspection.error if inspection.error
+
+          status = inspection.status
+          raise Error, format(DETACHED, name, status.head) if status.detached?
+
+          runtime.git.reflog(path, status.branch)
+        end
+
+        def cause(runtime, path, history, revision)
+          case revision.action
+          when nil then nil
+          when RolloutHistory::SYNC then "sync: fast-forward#{gained(runtime, path, revision)}"
+          when RolloutHistory::UNDO
+            undone = history.undone_to(revision)
+            undone ? "rollout undo to revision #{undone.number}" : RolloutHistory::UNDO
+          else revision.action
+          end
+        end
+
+        def gained(runtime, path, revision)
+          count = revision.from && runtime.git.commits_between(path, revision.from, revision.sha)
+          count ? " #{count} commit#{'s' unless count == 1}" : ''
+        end
+      end
+    end
+  end
+end