slipway 0.1.0

data/lib/slipway/syncer.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative 'command_line'
+require_relative 'drift'
+require_relative 'git'
+require_relative 'outcome'
+require_relative 'plan'
+require_relative 'rollout_history'
+
+module Slipway
+  # Brings projects to their manifests by the one move that cannot lose work: each is fetched,
+  # planned by Plan.for, and its checked-out branch fast-forwarded when the plan says so. It
+  # observes and plans on the workers and moves branches on the calling thread, one project at a
+  # time, so no two of its writes run at once.
+  class Syncer
+    # The plan for a project whose fetch went through, made from what git answered after it.
+    Observed = Data.define(:project, :inspection, :fetched, :plan)
+
+    FAST_FORWARDED = 'fast-forwarded'
+    REACHED = [Outcome::FETCHED, Outcome::UNCHANGED].freeze
+    ABBREV = Git::Porcelain::ABBREVIATION
+    TO_PIN = '(to the pinned revision)'
+    # Git leaves the branch where it was on each refusal. A lock may belong to a git that is
+    # still running, so none is ever removed.
+    ADVICE = { 'Busy' => 'sync never removes a lock', 'WouldOverwrite' => 'move them and run sync again',
+               'WouldLoseChanges' => 'commit or move them and run sync again',
+               'NotFastForward' => 'sync never merges or rebases' }.freeze
+
+    # Dry-run projects that no fetch has reached, counted as they settle.
+    attr_reader :unfetched
+
+    # `group` is the one a command without -n selects, so the undo command can leave it out; nil
+    # when -n was typed, so every undo command names its group.
+    def initialize(runtime, fetcher, dry_run:, group:)
+      @runtime = runtime
+      @fetcher = fetcher
+      @dry_run = dry_run
+      @group = group
+      @unfetched = 0
+    end
+
+    # Runs on a worker thread: an Outcome when nothing is left to do, else an Observed.
+    def observe(project)
+      return Outcome.new(project:, word: Outcome::PAUSED) if project.paused
+
+      inspection = @runtime.inspector.examine(project)
+      return unreadable(inspection) if inspection.error
+
+      fetched = @fetcher.fetch(project, inspection)
+      return fetched unless REACHED.include?(fetched.word)
+
+      inspection = @runtime.inspector.examine(project) unless @dry_run
+      return unreadable(inspection) if inspection.error
+
+      Observed.new(project:, inspection:, fetched:, plan: Plan.for(inspection))
+    end
+
+    # Runs on the calling thread, in the order the projects are listed.
+    def settle(step)
+      return step unless step.is_a?(Observed)
+
+      @unfetched += 1 if @dry_run && step.inspection.fetched_at.nil?
+      plan = step.plan
+      return skipped(step) unless plan.skips.empty?
+      return move(step) if plan.fast_forward?
+
+      still(step)
+    end
+
+    private
+
+    # The checks inside the fast-forward read the repository again right before git merges,
+    # and --ff-only is git's own last word.
+    def move(step)
+      project = step.project
+      plan = step.plan
+      return outcome(project, FAST_FORWARDED, drift(plan.items)) if @dry_run
+
+      onto = plan.to_revision? ? project.revision : Git::Repository::UPSTREAM
+      forward = @fetcher.exclusively(project) { @runtime.git.fast_forward(@fetcher.path(project), onto:) }
+      return still(step) unless forward.moved?
+
+      outcome(project, FAST_FORWARDED, [moved(step, forward), *declared(plan)])
+    rescue Git::Blocked => e
+      refused(step, e)
+    rescue Git::Error => e
+      Outcome.failure(project, e)
+    end
+
+    def moved(step, forward)
+      range = "#{step.inspection.status.branch} #{forward.from[0, ABBREV]}..#{forward.to[0, ABBREV]}"
+      return "#{range} #{TO_PIN}" if step.plan.to_revision?
+
+      gained = forward.count
+      undo = RolloutHistory.command('undo', step.project, @group)
+      "#{range} (#{gained} commit#{'s' unless gained == 1}); undo with '#{undo}'"
+    end
+
+    def refused(step, error)
+      reason = error.reason
+      detail = [error.message.delete_prefix("#{error.path}: "), ADVICE[reason]].compact.join('; ')
+      command = CommandLine.git(step.project, 'status') unless reason == 'Busy'
+      outcome(step.project, Outcome::SKIPPED, [detail, command, *declared(step.plan)], reason:)
+    end
+
+    def skipped(step)
+      blocker = step.plan.skips.first
+      outcome(step.project, Outcome::SKIPPED, [blocker.message, blocker.command, *declared(step.plan)],
+              reason: blocker.type)
+    end
+
+    # Nothing moved, so the plan's drift says why. Only a FetchOnly project reports what its fetch
+    # brought; for any other, sync reports the branch.
+    def still(step)
+      fetched = step.fetched if step.project.sync_policy == SyncPolicy::FETCH_ONLY
+      outcome(step.project, fetched&.word || Outcome::UNCHANGED,
+              [*fetched&.details, held(step), *drift(step.plan.reports)])
+    end
+
+    def held(step)
+      "held at #{step.project.revision[0, ABBREV]} by spec.revision" if step.inspection.at_pin?
+    end
+
+    # Worded as diff words it, with the command that shows or resolves it.
+    def unreadable(inspection)
+      item = Plan.for(inspection).items.first
+      outcome(inspection.project, Outcome::SKIPPED, [item.message, item.command], reason: item.type)
+    end
+
+    # A move or a blocker already says where the branch stands against its upstream or its pin.
+    def declared(plan) = drift(plan.reports.reject { Drift::MOVES.include?(it.type) })
+
+    def drift(items) = items.map { "#{it.type}: #{it.message}" }
+
+    def outcome(project, word, details, reason: nil)
+      Outcome.new(project:, word:, reason:, details: details.compact)
+    end
+  end
+end

data/lib/slipway/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Slipway
+  VERSION = '0.1.0'
+end

data/lib/slipway/views/group.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../labels'
+require_relative '../output'
+
+module Slipway
+  module Views
+    module Group
+      # See Views::Project::FIELDS.
+      FIELDS = { 'metadata.name' => '' }.freeze
+
+      def self.headers(wide: false, labels: false)
+        columns = %w[NAME PROJECTS AGE]
+        columns << 'DESCRIPTION' if wide
+        columns << 'LABELS' if labels
+        columns
+      end
+
+      def self.row(group, count:, now:, wide: false, labels: false)
+        cells = [group.name, count.to_s, Output::Age.humanize(group.created_at, now)]
+        cells << group.description if wide
+        cells << Labels.format(group.labels) if labels
+        cells
+      end
+
+      def self.describe(group, count:, now:)
+        [['Name', group.name], ['Labels', group.labels], ['Created', group.created_at],
+         ['Age', Output::Age.humanize(group.created_at, now)], ['Description', group.description],
+         ['Projects', count]]
+      end
+
+      def self.object(group, count:) = group.to_manifest.merge('status' => { 'projects' => count })
+    end
+  end
+end

data/lib/slipway/views/project.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative '../git/status'
+require_relative '../git/url'
+require_relative '../labels'
+require_relative '../plan'
+require_relative '../resources'
+require_relative '../state'
+require_relative '../output'
+
+module Slipway
+  module Views
+    module Project
+      DETACHED = '(detached)'
+      # A repository git could not read shows <none> in FETCHED, like its other cells, so
+      # <never> always means git answered and FETCH_HEAD records no fetch.
+      NEVER = '<never>'
+      ROLES = lambda do |header, value|
+        case header
+        when 'STATUS' then State.role(value)
+        when 'FETCHED' then :muted if value == NEVER
+        end
+      end
+      # The paths of #object a field selector may name, each with the value it compares as when
+      # the object leaves it out: kubectl compares an unset field as the empty string, while a
+      # missing lastFetch means no fetch is on record, which FETCHED shows as <never>.
+      FIELDS = { 'metadata.name' => '', 'metadata.group' => '', 'spec.path' => '', 'status.state' => '',
+                 'status.branch' => '', 'status.lastFetch' => 'never' }.freeze
+
+      def self.headers(wide: false, group: false, labels: false)
+        columns = [*(['GROUP'] if group), 'NAME', 'BRANCH', 'STATUS', 'FETCHED', 'AGE']
+        columns.push('PATH', 'HEAD', 'LAST-COMMIT', 'DRIFT') if wide
+        columns << 'LABELS' if labels
+        columns
+      end
+
+      # nil cells are fine: Table prints them as <none>.
+      def self.row(inspection, now:, wide: false, group: false, labels: false)
+        project = inspection.project
+        cells = [*([project.group] if group), project.name, branch(inspection.status), inspection.state,
+                 fetched(inspection, now), Output::Age.humanize(project.created_at, now)]
+        if wide
+          cells.push(project.path, inspection.status&.head, last_commit_age(inspection.commit, now),
+                     drift_types(inspection))
+        end
+        cells << Labels.format(project.labels) if labels
+        cells
+      end
+
+      def self.describe(inspection, now:)
+        project = inspection.project
+        [['Name', project.name], ['Group', project.group], ['Labels', project.labels],
+         ['Created', project.created_at], ['Age', Output::Age.humanize(project.created_at, now)],
+         ['Path', project.path], ['Description', project.description], *desired(project),
+         ['Status', Output::Painted.new(role: State.role(inspection.state), text: inspection.state)],
+         ['Repository', repository(inspection)], ['Last Commit', last_commit(inspection.commit)],
+         ['Drift', drift(inspection).map { [it.type, it.message] }]]
+      end
+
+      # Fields git could not answer are left out, as kubectl leaves out unset fields.
+      def self.object(inspection)
+        status = inspection.status
+        inspection.project.to_manifest.merge(
+          'status' => plain(
+            'branch' => status&.branch, 'head' => status&.head, 'upstream' => status&.upstream,
+            'ahead' => status&.ahead, 'behind' => status&.behind, 'staged' => status&.staged,
+            'unstaged' => status&.unstaged, 'untracked' => status&.untracked,
+            'conflicted' => status&.conflicted, 'stashes' => status&.stashes,
+            'state' => inspection.state, 'lastFetch' => Resources.timestamp(inspection.fetched_at),
+            'drift' => drift_object(inspection),
+            'lastCommit' => commit_object(inspection.commit)
+          ).compact
+        )
+      end
+
+      def self.desired(project)
+        [['Remote', project.remote&.then { Git::Url.redact(it) }], ['Branch', project.branch],
+         ['Revision', project.revision&.then { "#{it[0, Git::Porcelain::ABBREVIATION]} (pinned)" }],
+         ['Sync Policy', project.sync_policy], ['Paused', project.paused]]
+      end
+
+      def self.branch(status)
+        return nil if status.nil?
+
+        status.detached? ? DETACHED : status.branch
+      end
+
+      def self.fetched(inspection, now)
+        return nil if inspection.status.nil?
+
+        inspection.fetched_at ? Output::Age.humanize(inspection.fetched_at, now) : NEVER
+      end
+
+      def self.last_commit_age(commit, now) = commit && Output::Age.humanize(commit.time, now)
+
+      def self.drift(inspection) = Plan.for(inspection).items
+
+      def self.drift_types(inspection)
+        types = drift(inspection).map(&:type)
+        types.join(',') unless types.empty?
+      end
+
+      def self.drift_object(inspection)
+        drift(inspection).map { plain('type' => it.type, 'message' => it.message, 'blocker' => it.blocker) }
+      end
+
+      def self.repository(inspection)
+        status = inspection.status
+        return failure(inspection.error) if status.nil?
+
+        [['Branch', branch(status)], ['Head', status.head], ['Upstream', status.upstream],
+         ['Ahead', status.ahead], ['Behind', status.behind], ['Staged', status.staged],
+         ['Unstaged', status.unstaged], ['Untracked', status.untracked],
+         ['Conflicted', status.conflicted], ['Stashes', status.stashes],
+         ['Remote', inspection.remote&.then { Git::Url.redact(it) }], ['Last Fetch', last_fetch(inspection)]]
+      end
+
+      def self.last_fetch(inspection) = inspection.fetched_at || Output::Painted.new(role: :muted, text: NEVER)
+
+      # The Path line already shows the path, so it is cut from git's message.
+      def self.failure(error)
+        reason = error.message.delete_prefix("#{error.path}: ")
+        error.respond_to?(:hint) && error.hint ? [reason, error.hint] : reason
+      end
+
+      def self.last_commit(commit)
+        return nil if commit.nil?
+
+        [['Hash', commit.sha], ['Author', "#{commit.author} <#{commit.email}>"],
+         ['Date', Resources.timestamp(commit.time)], ['Subject', commit.subject]]
+      end
+
+      def self.commit_object(commit)
+        return nil if commit.nil?
+
+        plain('hash' => commit.sha, 'author' => commit.author, 'email' => commit.email,
+              'date' => Resources.timestamp(commit.time), 'subject' => commit.subject)
+      end
+
+      # json and yaml escape what their syntax needs, not what a terminal obeys, and `jq -r`
+      # prints a field as it is, so git's text is made plain here as it is in a table.
+      def self.plain(fields) = fields.transform_values { it.is_a?(String) ? Output.plain(it) : it }
+
+      private_class_method :desired, :branch, :fetched, :last_commit_age, :drift, :drift_types, :drift_object,
+                           :repository, :last_fetch, :failure, :last_commit, :commit_object, :plain
+    end
+  end
+end

data/lib/slipway/views.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'views/project'
+require_relative 'views/group'
+
+module Slipway
+  # Resources shaped for the renderers, one module per kind and no I/O.
+  module Views
+  end
+end

data/lib/slipway/yaml.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module Slipway
+  # The one YAML writer: manifests, `get -o yaml` and `config view` print the same dialect.
+  module Yaml
+    DOCUMENT_START = "---\n"
+
+    # line_width: -1 turns off Psych's line folding. The document marker is dropped, the way
+    # kubectl prints objects.
+    def self.dump(hash) = Psych.safe_dump(hash, line_width: -1).delete_prefix(DOCUMENT_START)
+  end
+end

data/lib/slipway.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'slipway/version'
+require_relative 'slipway/cli'
+require_relative 'slipway/paths'
+require_relative 'slipway/settings'
+require_relative 'slipway/editor'
+require_relative 'slipway/names'
+require_relative 'slipway/labels'
+require_relative 'slipway/selector'
+require_relative 'slipway/resources'
+require_relative 'slipway/schema'
+require_relative 'slipway/manifest'
+require_relative 'slipway/store'
+require_relative 'slipway/git'
+require_relative 'slipway/state'
+require_relative 'slipway/output'
+require_relative 'slipway/runtime'
+require_relative 'slipway/inspector'
+require_relative 'slipway/views'
+require_relative 'slipway/commands'
+
+# A kubectl-style registry of the git repositories on your machine.
+module Slipway
+  # Shared by exe/slipway and the tests, so it returns the exit status instead of exiting.
+  # `runtime_factory` is called only once a verb runs, with the context and the parsed options.
+  def self.run(argv, context: CLI::Context.system, runtime_factory: Runtime.method(:build))
+    registry = Commands.registry(runtime_factory)
+    color, theme = Runtime.color_defaults(context, argv)
+    CLI::Runner.new(registry, context, color:, theme:).run(argv)
+  end
+end

data/man/man1/slipway-api-resources.1

@@ -0,0 +1,53 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-API-RESOURCES" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-api\-resources \- Print the supported resource types
+.SH SYNOPSIS
+.SY "slipway api\-resources"
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Print the supported resource types.
+.PP
+Prints a table of the resource types slipway knows, sorted by name. A command accepts a type by its NAME, its singular or one of its SHORTNAMES. Type words are case\-insensitive. Use \-o wide to add the verbs that act on each type, and \-o name to print only the names.
+.SH OPTIONS
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fIFORMAT\fR
+Output format. One of: table, wide, name. (default "table")
+.TP
+\fB\-\-no\-headers\fR
+When using the default output format, don't print headers.
+.SH COLUMNS
+Every type shows NAME, SHORTNAMES, KIND and GROUPED, and \-o wide adds VERBS. A type without aliases reads <none> in SHORTNAMES.
+.TP
+\fBNAME\fR
+The name of the type, in the plural.
+.TP
+\fBSHORTNAMES\fR
+The aliases of the type, besides its singular.
+.TP
+\fBKIND\fR
+The kind a manifest of the type declares.
+.TP
+\fBGROUPED\fR
+Whether resources of the type live in a group, so that \-n and \-A scope them. kubectl's NAMESPACED column says the same about namespaces.
+.TP
+\fBVERBS\fR
+The commands that act on resources of the type.
+.SH EXAMPLES
+.EX
+# Print the supported resource types
+slipway api\-resources
+.EE
+.PP
+.EX
+# Print the supported resource types with more information
+slipway api\-resources \-o wide
+.EE
+.PP
+.EX
+# Print the names of the supported resource types
+slipway api\-resources \-o name
+.EE
+.SH "SEE ALSO"
+.BR slipway (1)

data/man/man1/slipway-apply.1

@@ -0,0 +1,45 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-APPLY" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-apply \- Apply a configuration to a resource by file name or stdin
+.SH SYNOPSIS
+.SY "slipway apply"
+.B \-f
+.I FILE
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Apply a configuration to a resource by file name or stdin.
+.PP
+The resource name must be specified in the manifest. A resource is created when it does not exist yet, configured when its manifest differs from the one stored, and reported unchanged otherwise. A directory applies every *.yaml and *.yml file it holds, sorted by name and without descending into subdirectories. A project manifest without metadata.group lands in the current group.
+.PP
+YAML is accepted, with several documents per file, and a document of kind List stands for each of its items. Documents are applied in order, so a group may be created by the document before the projects that use it.
+.SH OPTIONS
+.TP
+\fB\-f\fR, \fB\-\-filename\fR \fIFILE\fR
+The file that contains the manifests to apply; may be repeated. A directory reads its *.yaml and *.yml files, '\-' reads stdin. (required)
+.TP
+\fB\-\-dry\-run\fR
+Print what would change and write nothing.
+.SH EXAMPLES
+.EX
+# Apply the configuration in hldr.yaml to a project
+slipway apply \-f hldr.yaml
+.EE
+.PP
+.EX
+# Apply every manifest in a directory
+slipway apply \-f ./projects
+.EE
+.PP
+.EX
+# Apply the YAML passed into stdin
+slipway apply \-f \- < hldr.yaml
+.EE
+.PP
+.EX
+# Show what would change without writing anything
+slipway apply \-f hldr.yaml \-\-dry\-run
+.EE
+.SH "SEE ALSO"
+.BR slipway (1)

data/man/man1/slipway-completion.1

@@ -0,0 +1,29 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-COMPLETION" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-completion \- Output shell completion code for the specified shell (bash, zsh, fish)
+.SH SYNOPSIS
+.SY "slipway completion"
+.I SHELL\&
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Output shell completion code for the specified shell (bash, zsh, fish).
+The shell code must be evaluated to provide interactive completion of commands, resource types and names.
+.SH EXAMPLES
+.EX
+# Install bash completions where bash\-completion loads them
+slipway completion bash > "${XDG_DATA_HOME:\-$HOME/.local/share}/bash\-completion/completions/slipway"
+.EE
+.PP
+.EX
+# Install zsh completions in a directory on your fpath
+slipway completion zsh > ~/.zfunc/_slipway
+.EE
+.PP
+.EX
+# Install fish completions
+slipway completion fish > ~/.config/fish/completions/slipway.fish
+.EE
+.SH "SEE ALSO"
+.BR slipway (1)

data/man/man1/slipway-config-path.1

@@ -0,0 +1,20 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-CONFIG-PATH" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-config\-path \- Display the path of the configuration file
+.SH SYNOPSIS
+.SY "slipway config path"
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Display the path of the configuration file.
+.PP
+Prints the file that slipway reads: \-\-config, then SLIPWAY_CONFIG, then $XDG_CONFIG_HOME/slipway/config.yaml. When the default file does not exist, its path is still printed and a note on stderr says so; a file named by \-\-config or SLIPWAY_CONFIG must exist.
+.SH EXAMPLES
+.EX
+# Print the path of the configuration file
+slipway config path
+.EE
+.SH "SEE ALSO"
+.BR slipway (1),
+.BR slipway\-config (1)

data/man/man1/slipway-config-view.1

@@ -0,0 +1,25 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-CONFIG-VIEW" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-config\-view \- Display the configuration in effect
+.SH SYNOPSIS
+.SY "slipway config view"
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Display the configuration in effect.
+.PP
+Prints every setting as YAML after applying the precedence flag, then SLIPWAY_* environment variable, then configuration file, then built\-in default. The first line names the configuration file that was consulted, and says (not found) when the default file does not exist. A file named by \-\-config or SLIPWAY_CONFIG must exist.
+.SH EXAMPLES
+.EX
+# Show the settings in effect
+slipway config view
+.EE
+.PP
+.EX
+# Show the settings another file would give
+slipway config view \-\-config ~/work/slipway.yaml
+.EE
+.SH "SEE ALSO"
+.BR slipway (1),
+.BR slipway\-config (1)

data/man/man1/slipway-config.1

@@ -0,0 +1,22 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-CONFIG" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-config \- Inspect the configuration in effect
+.SH SYNOPSIS
+.SY "slipway config"
+.I COMMAND
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Inspect the configuration that slipway resolved from flags, environment variables and the configuration file.
+.SH COMMANDS
+.TP 6
+\fBview\fR
+Display the configuration in effect
+.TP 6
+\fBpath\fR
+Display the path of the configuration file
+.SH "SEE ALSO"
+.BR slipway (1),
+.BR slipway\-config\-view (1),
+.BR slipway\-config\-path (1)

data/man/man1/slipway-create.1

@@ -0,0 +1,89 @@
+.\" Generated by slipway 0.1.0. Do not edit.
+.TH "SLIPWAY-CREATE" "1" "2026-09-30" "slipway 0.1.0" "Slipway Manual"
+.SH NAME
+slipway\-create \- Create a resource by name
+.SH SYNOPSIS
+.SY "slipway create"
+.I "(TYPE NAME | project \-\-from\-dir DIR)"\&
+.RI [ flags ]
+.YS
+.SH DESCRIPTION
+Create a resource by name.
+.PP
+A project registers the git repository at \-\-path in the current group, which must exist unless it is the default group. A group is created empty and holds the projects you register with \-\-group later.
+.PP
+With \-\-from\-dir DIR in place of NAME, create project registers every git repository at DIR or under it, down to \-\-depth levels. Each project is named after its directory, lowercased with each run of characters other than ASCII letters, digits and dashes made one dash, and records its path and the URL of its origin without any credentials; the checked\-out branch is not recorded. A path the group already holds is reported unchanged, so running it again adds only new clones.
+.PP
+Use \-\-dry\-run to check the arguments without writing anything, and \-o yaml with it to print the manifest instead, ready for apply \-f.
+.PP
+Resource types: projects (project, proj) and groups (group). Type words are case\-insensitive.
+.SH OPTIONS
+.TP
+\fB\-\-path\fR \fIDIR\fR
+Directory of the git repository to register; required for a project given by NAME. A relative directory is stored resolved against the current directory, a ~ path as written.
+.TP
+\fB\-\-description\fR \fITEXT\fR
+A short description of the resource.
+.TP
+\fB\-\-label\fR \fIKEY=VALUE\fR
+A label to set on the new resource; may be repeated.
+.TP
+\fB\-\-remote\fR \fIURL\fR
+The URL the origin remote is expected to have, written to spec.remote. A URL that embeds credentials is refused; use a credential helper.
+.TP
+\fB\-\-branch\fR \fINAME\fR
+The branch the project is expected to have checked out, written to spec.branch.
+.TP
+\fB\-\-from\-dir\fR \fIDIR\fR
+Register every git repository at or under DIR as a project, in place of NAME.
+.TP
+\fB\-\-depth\fR \fIN\fR
+How many directory levels under \-\-from\-dir to search, from 1 to 8. The search stops at a repository and never follows a symbolic link under \-\-from\-dir. (default 1)
+.TP
+\fB\-\-dry\-run\fR
+Print what would change and write nothing.
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fIFORMAT\fR
+Output format; without it, each resource prints a result line such as project/hldr created. One of: json, yaml, name.
+.SH EXAMPLES
+.EX
+# Register the repository at ~/dev/hldr as a project in the current group
+slipway create project hldr \-\-path '~/dev/hldr'
+.EE
+.PP
+.EX
+# Register a project in the work group with two labels
+slipway create project api \-\-path '~/work/api' \-n work \-\-label lang=go \-\-label tier=api
+.EE
+.PP
+.EX
+# Register a project with the remote and the branch it is expected to have
+slipway create project hldr \-\-path '~/dev/hldr' \-\-remote git@github.com:hvpaiva/hldr.git \-\-branch main
+.EE
+.PP
+.EX
+# Create a group with a description
+slipway create group work \-\-description "Projects for the day job"
+.EE
+.PP
+.EX
+# Check the arguments without writing the project
+slipway create project hldr \-\-path '~/dev/hldr' \-\-dry\-run
+.EE
+.PP
+.EX
+# Print the manifest of a project without registering it
+slipway create project hldr \-\-path '~/dev/hldr' \-\-dry\-run \-o yaml
+.EE
+.PP
+.EX
+# Register every repository in ~/dev/personal in the personal group
+slipway create project \-\-from\-dir ~/dev/personal \-n personal
+.EE
+.PP
+.EX
+# Write the manifests of the repositories two levels under ~/work to a file
+slipway create project \-\-from\-dir ~/work \-\-depth 2 \-\-dry\-run \-o yaml > work.yaml
+.EE
+.SH "SEE ALSO"
+.BR slipway (1)