gitflash 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37431db670588b8025d973c045532de047b33a667fc1c86152e1180d2d0a01a6
-  data.tar.gz: 307fe7991415b2bedce69a08f7b0e09e591be3cbcb6be692c1d46c87c79019b1
+  metadata.gz: f754910573873164cbdb81ddd5191e9c472db9b482df20072e5ea4e7c5473f95
+  data.tar.gz: 764369b4f40ff33aaf2576721d58fafe54a7bda777e00e84387b008a3a9d006a
 SHA512:
-  metadata.gz: dcc8b7a6a6c740c46c78d29766bc78b99fa9949217482a71e47070a077a51759903c74a82adbcbe24590e27dbc04f5db5501175efda1a2a624f7b84211e72579
-  data.tar.gz: 541587b9f335e4ccd47f4cb0e7ec9806d1e4a2abb06d8811e81e8c483c2eba2126c26f7cbaebe5074d07d968d4e156b6ea751ccfbff08b6128a6239af0cd4272
+  metadata.gz: f0fa13de63f9418c5acec24af7e645927ee502e63401e36288b4d478e8d17d5d41bfe762e4055dc9fe67915c6b466d755a61ceb885a9f0c9e31d4d8a6abe4f23
+  data.tar.gz: a4c00a408fced68c41d503711ee5204df1bd978d14fe0b5b9a02a6d53e3b54a1a8381a930b87c86c5cd67ce239711a7b002e8931bcb184edab2f2fb1b1849e3d

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+## [0.1.0.alpha] - 2023-06-17
+
+- Initial release
+
+## [0.1.1.alpha] - 2023-10-28
+
+- Fix delete method
+- Added and updated test
+- bug fixes
+
+## [0.1.2.alpha] - 2023-11-4
+
+- Refactors and code improvements
+- Zeitwerk warning suppress
+- Update README
+- Bug fixes
+
+## [0.2.0.alpha] - 2023-12-9
+
+- Add reset command
+- Code improvements
+
+## [0.3.0] - 2025-10-10
+
+- Fix reset method
+- Update to Ruby version 3.3.2
+- Bug fixes
+
+## [0.4.0] - 2026-09-24
+
+- Run git commands without a shell and raise on failure
+- List branches with `git for-each-ref`; detached HEAD no longer shows as a branch
+- List the latest 100 commits for `reset`, unaffected by `log.decorate`
+- Exit with an error when a git command fails or outside a git repository
+- `delete` does nothing when no branches are available or selected
+- `reset --hard` prints `Exited` when declined; fix single-commit message
+- Correct `reset` help text
+- Portable `bin/gitflash` shebang
+- Require thor >= 1.4 (CVE-2025-54314) and Ruby >= 3.3
+- Add `version` command (`--version`, `-v`)
+- CI: pin third-party action to a commit SHA, restrict token permissions, test Ruby 3.3–3.4
+
+## [0.5.0] - 2026-10-03
+
+- Add `branches` command with last commit, upstream (ahead, behind, gone) and merge status, filters `--merged`, `--gone`, `--stale DAYS`
+- Commands accept arguments: `checkout BRANCH`, `delete BRANCH...`, `reset COMMIT`
+- Add `--json`, `--yes` and `--dry-run` options to every command
+- Never wait for input without a terminal: exit with code 2 and explain what to pass
+- `delete` keeps unmerged branches unless `--force` is given (breaking: it used to always force-delete) and also protects the default branch
+- Detect the default branch from `origin/HEAD`, falling back to `main` or `master`
+- Add `reset --soft`
+- JSON contract version 1: every `--json` run prints one envelope (`schema`, `command`, `ok`, `status`, `dry_run`, `plan`, `result`, `error`) defined in `schema/v1.json`; stable error codes
+- Results include what is needed to revert: deleted branch SHAs, the previous branch after `checkout`, the previous commit after `reset`
+- Add `schema` command that prints the JSON Schema
+- Internal: new `Repo` service layer with `Branch` and `Commit` records; integration specs run against real temporary git repositories

data/README.md

@@ -2,9 +2,11 @@
 
 [![Gem Version](https://badge.fury.io/rb/gitflash.svg)](https://badge.fury.io/rb/gitflash)
 
-⚠️ **This project is stil under development**: Use at your own risk!
+⚠️ **This project is still under development**: Use at your own risk!
 
-This gem allows you to use some of the most common git commands in a more user intuitive way.
+A safety net and cleanup tool for git repositories that AI coding agents work in. It works on plain git, with nothing new to adopt, and every command can be run by a person in a terminal or by an agent with a stable JSON contract.
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for where the project is going.
 
 ## Installation
 
@@ -24,10 +26,67 @@ Or install it yourself as:
 
 ## Requirements
 
-This gem requires Ruby 3.3.2+.
+This gem requires Ruby 3.3+ and git.
+
 ## Usage
 
-Run `gitflash` to get a list with the available commands and their description.
+Run `gitflash` inside a git repository to get a list with the available commands and their description.
+
+| Command | Description |
+| --- | --- |
+| `gitflash branches` | List local branches with last commit, upstream status and merge status. Filter with `--merged`, `--gone` or `--stale DAYS` |
+| `gitflash checkout [BRANCH]` | Check out a branch, or pick one from a list |
+| `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current, default, `main` and `master` branches are protected. Unmerged branches are kept unless you pass `--force` |
+| `gitflash reset [COMMIT]` | Reset to a commit, or pick one of the latest 100. Mixed by default; `--soft` keeps changes staged, `--hard` discards them after confirmation |
+| `gitflash schema` | Print the JSON Schema of the `--json` output |
+| `gitflash version` | Print the installed version (also `--version`, `-v`) |
+
+Without an argument, a command shows an interactive list. With arguments it runs directly, which also works in scripts.
+
+Options for every command:
+
+| Option | Effect |
+| --- | --- |
+| `--json` | Print JSON instead of text. Never shows lists or prompts |
+| `--yes`, `-y` | Skip confirmation prompts |
+| `--dry-run` | Show what would happen without changing anything |
+
+Run `gitflash help <command>` for details on a command.
+
+### Scripts and AI agents
+
+Without a terminal (for example in a script, CI or an AI coding agent), gitflash never waits for input:
+
+- A command that needs a list selection fails with exit code 2 and says which argument to pass.
+- A destructive action (`delete`, `reset --hard`) fails with exit code 2 and returns the plan unless you pass `--yes`.
+
+With `--json`, every command prints one object in the same envelope, defined in [schema/v1.json](schema/v1.json) (also printed by `gitflash schema`):
+
+```json
+{
+  "schema": 1,
+  "command": "delete",
+  "ok": true,
+  "status": "done",
+  "dry_run": false,
+  "plan": { "branches": ["old-feature"], "force": false },
+  "result": { "deleted": [{ "branch": "old-feature", "sha": "3551cba" }], "failed": [] }
+}
+```
+
+- `status`: `done`, `planned` (`--dry-run`), `noop`, `cancelled`, `failed`, `confirmation_required` or `error`. `ok` is true for the first four.
+- `result` includes what you need to revert: the SHA of each deleted branch (`git branch NAME SHA`), the previous branch after `checkout`, the previous commit after `reset`.
+- `error.code` is a stable identifier such as `unknown_branch`, `protected_branch` or `confirmation_required`.
+
+```bash
+gitflash branches --merged --json
+```
+
+```bash
+gitflash delete old-feature another-branch --yes --json
+```
+
+Exit codes: `0` success, `1` a git command failed (for example a branch was not fully merged), `2` invalid usage or confirmation required.
 
 ## Development
 

data/bin/gitflash

@@ -1,4 +1,5 @@
-#!/usr/bin/env ruby -wU
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'gitflash'
 require 'gitflash/cli'

data/command_descriptions.yml

@@ -1,33 +1,48 @@
+branches:
+  short: 'List local branches with merge and upstream status'
+  long: |
+    Lists local branches with their last commit, upstream status (ahead, behind, gone)
+    and whether they are merged into the default branch.
+
+    The default branch is the one origin/HEAD points to, else main or master.
+
+    Filters (a branch is listed when it matches any of them):
+      --merged      merged into the default branch
+      --gone        upstream branch was deleted on the remote
+      --stale DAYS  no commits for DAYS days
+
+    Pass --json for machine-readable output.
+
 checkout:
-  short: 'Checkout the selected branch'
+  short: 'Checkout a branch'
   long: |
-    Presents a list with all the available local branches.
+    Checks out BRANCH when given.
 
-    You can use the arrow keys to navigate through the branches.
-    Type for quick searching a specific branch.
-    Press `enter` to choose and checkout the branch.
-    Press `ctrl+c` to cancel the operation.
+    Without BRANCH, presents a list with all the available local branches:
+    use the arrow keys to navigate, type to search, press `enter` to checkout
+    and `ctrl+c` to cancel. Without a terminal, BRANCH is required.
 
 delete:
-  short: 'Delete the selected branches'
+  short: 'Delete branches'
   long: |
-    Presents a list with all the available local branches (without current or main/master).
+    Deletes the given BRANCHES. Without them, presents a list with the local branches
+    (without the current, default, main or master branch): press `space` to choose
+    branches and `enter` to confirm. Without a terminal, BRANCHES are required.
+
+    Branches with unmerged changes are kept unless --force is given.
 
-    You can use the arrow keys to navigate through the branches.
-    Type for quick searching a specific branch.
-    Press `space` to choose multiple branches.
-    Press `enter` to confirm selection and delete branches.
-    Press `ctrl+c` to cancel the operation.
+    Asks for confirmation before deleting. Pass --yes to skip it, which is required
+    without a terminal, or --dry-run to only show what would be deleted.
 
 reset:
-  short: 'Reset your code to the selected commit'
+  short: 'Reset your code to a commit'
   long: |
-    Accepts an optional parameter (hard) if you want to hard reset.
+    Resets the current branch to COMMIT when given.
 
-    Presents a list with all the available commits.
+    Without COMMIT, presents a list with the latest 100 commits of the current branch:
+    use the arrow keys to navigate, type to search, press `enter` to reset to that commit
+    and `ctrl+c` to cancel. Without a terminal, COMMIT is required.
 
-    You can use the arrow keys to navigate through the commits.
-    Type for quick searching a specific commit.
-    Press `space` to choose multiple commits.
-    Press `enter` to confirm selection and reset to that commit.
-    Press `ctrl+c` to cancel the operation.
+    By default performs a mixed reset: your changes are kept as unstaged changes.
+    Pass --soft to keep them staged, or --hard to discard them. A hard reset asks for
+    confirmation; pass --yes to skip it, which is required without a terminal.

data/lib/gitflash/branch.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Gitflash
+  # A local branch as reported by `git for-each-ref`
+  Branch = Data.define(
+    :name, :sha, :current, :default, :upstream, :upstream_gone, :ahead, :behind,
+    :merged, :last_commit_at, :last_commit_author, :last_commit_subject
+  ) do
+    # Parses one line produced with Repo::BRANCH_FORMAT.
+    # `merged_names` is nil when merge status is unknown.
+    def self.parse(line, default_branch: nil, merged_names: nil)
+      name, sha, head, upstream, track, date, author, subject = line.split(Repo::SEPARATOR, 8)
+
+      new(
+        name: name,
+        sha: sha,
+        current: head == '*',
+        default: name == default_branch,
+        upstream: upstream.to_s.empty? ? nil : upstream,
+        upstream_gone: track == 'gone',
+        ahead: track.to_s[/ahead (\d+)/, 1].to_i,
+        behind: track.to_s[/behind (\d+)/, 1].to_i,
+        merged: merged_names&.include?(name),
+        last_commit_at: Time.iso8601(date),
+        last_commit_author: author,
+        last_commit_subject: subject.to_s
+      )
+    end
+
+    alias_method :current?, :current
+    alias_method :default?, :default
+    alias_method :upstream_gone?, :upstream_gone
+
+    def stale?(days, now: Time.now)
+      last_commit_at < now - (days * 86_400)
+    end
+
+    def to_h
+      super.merge(last_commit_at: last_commit_at.iso8601)
+    end
+  end
+end

data/lib/gitflash/cli.rb

@@ -6,113 +6,77 @@ module Gitflash
   class Cli < Thor
     extend Configuration::Descriptions
 
+    SCHEMA_PATH = File.expand_path('../../schema/v1.json', __dir__)
+
     def self.exit_on_failure?
       true
     end
 
-    desc 'checkout', descriptions.checkout.short
-    long_desc descriptions.checkout.long
-
-    def checkout
-      branches? ? checkout_branch : prompt.ok('You only have one branch!')
-    end
-
-    desc 'delete', descriptions.delete.short
-    long_desc descriptions.delete.long
-
-    def delete
-      branches? ? delete_branch : prompt.ok('You only have one branch!')
-    end
-
-    desc 'reset', descriptions.reset.short
-    long_desc descriptions.reset.long
-
-    option :hard, type: :boolean, default: false, desc: 'Perform a hard reset'
-    def reset
-      commits? ? reset_to_commit : prompt.ok('You only have one branch!')
-    end
-
-    private
-
-    def checkout_branch
-      selection = prompt.select(
-        'Select a branch to checkout',
-        branches,
-        **checkout_options
-      )
+    class_option :json, type: :boolean, default: false,
+                        desc: 'Print JSON instead of text; never prompts'
+    class_option :yes, type: :boolean, aliases: '-y', default: false,
+                       desc: 'Skip confirmation prompts'
+    class_option :dry_run, type: :boolean, default: false,
+                           desc: 'Show what would happen without changing anything'
 
-      git.checkout(selection)
+    desc 'branches', descriptions.branches.short
+    long_desc descriptions.branches.long
+    option :merged, type: :boolean, desc: 'Branches merged into the default branch'
+    option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
+    option :stale, type: :numeric, banner: 'DAYS', desc: 'Branches without commits for DAYS days'
+    def branches
+      run_command(Commands::Branches)
     end
 
-    def delete_branch
-      selection = prompt.multi_select(
-        'Select branches to delete',
-        branches(options: { master: false, current: false })
-      )
-
-      warning_message = <<~TEXT
-        You are about to permanently delete the following branches even if they have unmerged changes:
-
-        #{selection.map { |br| "* #{br}" }.join("\n")}
-      TEXT
-
-      prompt_proceed_warning(warning_message) { git.delete(selection) }
-    end
-
-    def reset_to_commit
-      selection = prompt.select('Select a commit to reset to', branch_commits)
-      reset_options = { commit_hash: selection, hard: options[:hard] }
-
-      if options[:hard]
-        warning_message = 'You are about to reset your branch and lose all your current changes'
-        prompt.proceed_with_warning(warning_message) { git.reset(**reset_options) }
-      else
-        git.reset(**reset_options)
-      end
-    end
-
-    def branches?
-      all_branches && all_branches.size > 1
-    end
-
-    def commits?
-      branch_commits && branch_commits.size > 1
+    desc 'checkout [BRANCH]', descriptions.checkout.short
+    long_desc descriptions.checkout.long
+    def checkout(branch = nil)
+      run_command(Commands::Checkout, *[branch].compact)
     end
 
-    def prompt
-      @prompt ||= Prompt.create
+    desc 'delete [BRANCH...]', descriptions.delete.short
+    long_desc descriptions.delete.long
+    option :force, type: :boolean, default: false,
+                   desc: 'Delete branches even if they have unmerged changes'
+    def delete(*branches)
+      run_command(Commands::Delete, *branches)
     end
 
-    def prompt_proceed_warning(message)
-      prompt.warn(message)
-      answer = prompt.yes?('Do you want to proceed?')
-      puts answer ? yield : 'Exited'
+    desc 'reset [COMMIT]', descriptions.reset.short
+    long_desc descriptions.reset.long
+    option :hard, type: :boolean, default: false, desc: 'Discard all current changes'
+    option :soft, type: :boolean, default: false, desc: 'Keep changes staged'
+    def reset(commit = nil)
+      run_command(Commands::Reset, *[commit].compact)
     end
 
-    def checkout_options
-      {}.tap do |opt|
-        opt[:default] = current unless current.nil?
-      end
+    desc 'schema', 'Print the JSON Schema of the --json output'
+    def schema
+      puts File.read(SCHEMA_PATH)
     end
 
-    def branches(options: {})
-      git.local_branches(**options)
-    end
+    desc 'version', 'Print the gitflash version'
+    map %w[--version -v] => :version
 
-    def all_branches
-      @all_branches ||= git.all_local_branches
+    def version
+      puts VERSION
     end
 
-    def current
-      @current ||= git.current_branch
-    end
+    private
 
-    def branch_commits
-      @branch_commits = git.branch_commits
+    def run_command(command_class, *)
+      ui = build_ui(command_class.name.split('::').last.downcase)
+      repo = Repo.new
+      repo.ensure_work_tree!
+      status = command_class.new(repo: repo, ui: ui, options: options).call(*)
+      exit(status) unless status.zero?
+    rescue Error => e
+      ui.error(e)
+      exit(e.exit_code)
     end
 
-    def git
-      Gitflash::Git::Wrapper
+    def build_ui(command)
+      Ui.new(command: command, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
     end
   end
 end

data/lib/gitflash/commands/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Shared setup for commands. `call` returns the process exit status.
+    class Base
+      def initialize(repo:, ui:, options: {})
+        @repo = repo
+        @ui = ui
+        @options = options
+      end
+
+      private
+
+      attr_reader :repo, :ui, :options
+
+      def require_interactive!(message)
+        usage_error!('input_required', message) unless ui.interactive?
+      end
+
+      def usage_error!(code, message)
+        raise UsageError.new(message, code: code)
+      end
+
+      def git_error!(command, result)
+        raise Error.new("git #{command} failed:\n#{result.output}", code: 'git_failed')
+      end
+
+      def planned(plan, text)
+        ui.report(status: 'planned', plan: plan, text: text)
+      end
+
+      def cancelled(plan)
+        ui.report(status: 'cancelled', plan: plan, text: 'Exited')
+      end
+    end
+  end
+end

data/lib/gitflash/commands/branches.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Lists local branches, optionally filtered to merged, gone or stale ones
+    class Branches < Base
+      def call
+        branches = filter(repo.branches(merged_status: true))
+        result = { default_branch: repo.default_branch, branches: branches.map(&:to_h) }
+        ui.report(status: 'done', result: result, text: table(branches))
+      end
+
+      private
+
+      # A branch is listed when it matches any of the given filters
+      def filter(branches)
+        filters = active_filters
+        return branches if filters.empty?
+
+        branches.select { |branch| filters.any? { |matches| matches.call(branch) } }
+      end
+
+      def active_filters
+        filters = {
+          merged: ->(branch) { branch.merged && !branch.default? },
+          gone: lambda(&:upstream_gone?),
+          stale: ->(branch) { branch.stale?(options[:stale]) }
+        }
+        filters.select { |name, _filter| options[name] }.values
+      end
+
+      def table(branches)
+        return 'No branches match.' if branches.empty?
+
+        width = branches.map { |branch| branch.name.length }.max
+        branches.map { |branch| row(branch, width) }.join("\n")
+      end
+
+      def row(branch, width)
+        marker = branch.current? ? '*' : ' '
+        columns = [
+          "#{marker} #{branch.name.ljust(width)}",
+          age(branch.last_commit_at).ljust(12),
+          status(branch).ljust(22),
+          branch.last_commit_subject
+        ]
+        columns.join('  ').rstrip
+      end
+
+      def status(branch)
+        {
+          'default' => branch.default?,
+          'merged' => branch.merged && !branch.default?,
+          'gone' => branch.upstream_gone?,
+          "ahead #{branch.ahead}" => branch.ahead.positive?,
+          "behind #{branch.behind}" => branch.behind.positive?
+        }.select { |_label, shown| shown }.keys.join(', ')
+      end
+
+      def age(time)
+        days = ((Time.now - time) / 86_400).floor
+        return 'today' if days < 1
+
+        days == 1 ? '1 day ago' : "#{days} days ago"
+      end
+    end
+  end
+end

data/lib/gitflash/commands/checkout.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Checks out a local branch given as an argument or picked from a menu
+    class Checkout < Base
+      def call(name = nil)
+        branches = repo.branches
+        current = branches.find(&:current?)&.name
+
+        if name.nil?
+          require_interactive!('Pass the branch to check out: gitflash checkout BRANCH')
+          return noop(current, 'You only have one branch!') if branches.size < 2
+
+          name = pick(branches, current)
+        end
+
+        checkout(name, branches.map(&:name), current)
+      end
+
+      private
+
+      def pick(branches, current)
+        select_options = current.nil? ? {} : { default: current }
+        ui.select('Select a branch to checkout', branches.map(&:name), **select_options)
+      end
+
+      def checkout(name, names, current)
+        usage_error!('unknown_branch', "Unknown branch '#{name}'") unless names.include?(name)
+        return noop(name, "Already on '#{name}'") if name == current
+
+        plan = { branch: name }
+        return planned(plan, "Would check out '#{name}'") if ui.dry_run?
+
+        result = repo.checkout(name)
+        git_error!('checkout', result) unless result.success?
+
+        ui.report(status: 'done', plan: plan, result: { branch: name, previous_branch: current },
+                  text: "Switched to branch '#{name}'")
+      end
+
+      def noop(branch, text)
+        ui.report(status: 'noop', result: { branch: branch, previous_branch: branch }, text: text)
+      end
+    end
+  end
+end