braid 1.1.7 → 1.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad14f6dd7a5d428c5796bbd19039aae6e59f5803d93da3889fe0a92a8afd032b
-  data.tar.gz: 9d6bcfd73c5a306f853e6b9653edda5aff6a7bbd3541b6ab644bd7b96bc510e6
+  metadata.gz: 0ddcc3421c5a2dffcf7634e71118d7392d9f506ab49064f25eb2c38f7f0d67b1
+  data.tar.gz: d3ad647f242d287ece52de41be7edb56cfdc3c469336ee84bb35c15257ca4d36
 SHA512:
-  metadata.gz: 817cd08525921352f103a81f05b6c550e8eaff62fb647c04d0ecb746e6ed425a78ef1bea4a477786675c406b0e23982f36a52eea205278a3b25ccee6e64ecdf5
-  data.tar.gz: 76d9e62b1d58a437a8eae77f879b5a66ec6a30cda270d267cc458e621a3f1560fa192f5cc435b5e718c9f093691464d458b049d2e236864d0faea6e801c89629
+  metadata.gz: f002d88fa8bb752ab878d746c8b1ead6c73b80518d37a06f261eba2b99540c6081c7991a9f404ec0ca26c39165b6e9345725e4b4f49f52ad132ca1e359465e39
+  data.tar.gz: 4da0947c03c1846b073b331f4118f8b07e42b4138c3450b3f2ce6ba967e3a8451edf843622e3e6b6bbe4f5c70951866d7c6abbcc7e1211d10501b75fefa8e095

data/lib/braid/check_gem.rb

@@ -1,3 +1,10 @@
+# Since this file can't safely depend on the Sorbet runtime, it isn't prudent to
+# try to commit to `typed: true` even if the file currently passes type checking
+# without needing any references to `T`.  Like `exe/braid`, this file doesn't
+# have much code worth type checking.
+#
+# typed: false
+
 # Braid has several entry points that run code from Ruby gems (either Braid
 # itself or dependencies such as Sorbet) and expect to get the correct versions
 # (either the same copy of Braid or versions of dependencies consistent with the

data/lib/braid/command.rb

@@ -17,6 +17,11 @@ module Braid
       klass.new.run(*args)
 
     rescue BraidError => error
+      handle_error(error)
+    end
+
+    sig {params(error: BraidError).returns(T.noreturn)}
+    def self.handle_error(error)
       case error
         when Operations::ShellExecutionError
           msg "Shell error: #{error.message}"
@@ -36,6 +41,7 @@ module Braid
       self.class.msg(str)
     end
 
+    sig {returns(Config)}
     def config
       @config ||= Config.new({'mode' => config_mode})
     end

data/lib/braid/commands/add.rb

@@ -1,15 +1,55 @@
+# typed: true
 module Braid
   module Commands
     class Add < Command
+      # Returns the default branch name of the repository at the given URL, or
+      # nil if it couldn't be determined.
+      #
+      # We won't be able to determine a default branch in certain cases that we
+      # expect to be unusual in the context of Braid, such as if the HEAD is
+      # detached or points to a ref outside of `refs/heads`.  (Presumably, the
+      # same thing happens if the server is too old to report symrefs to us.)
+      # In those cases, a plausible alternative behavior would be to just lock
+      # the mirror to the remote HEAD revision, but that's probably not what the
+      # user wants.  It's much more likely that something is wrong and Braid
+      # should report an error.
+      def get_default_branch_name(url)
+        head_targets = []
+        # The `HEAD` parameter here doesn't appear to do an exact match (it
+        # appears to match any ref with `HEAD` as the last path component, such
+        # as `refs/remotes/origin/HEAD` in the unusual case where the repository
+        # contains its own remote-tracking branches), but it reduces the data we
+        # have to scan a bit.
+        git.ls_remote(['--symref', url, 'HEAD']).split("\n").each do |line|
+          m = /^ref: (.*)\tHEAD$/.match(line)
+          head_targets.push(m[1]) if m
+        end
+        return nil unless head_targets.size == 1
+        m = /^refs\/heads\/(.*)$/.match(head_targets[0])
+        return nil unless m
+        m[1]
+      end
+
       def run(url, options = {})
         with_reset_on_error do
+          if options['branch'].nil? && options['tag'].nil? && options['revision'].nil?
+            default_branch = get_default_branch_name(url)
+            if default_branch.nil?
+              raise BraidError, <<-MSG
+Failed to detect the default branch of the remote repository.  Please specify
+the branch you want to use via the --branch option.
+MSG
+            end
+            options['branch'] = default_branch
+          end
+
           mirror           = config.add_from_options(url, options)
           add_config_file
 
           mirror.branch = nil if options['revision']
           raise BraidError, 'Can not add mirror specifying both a revision and a tag' if options['revision'] && mirror.tag
 
-          branch_message   = (mirror.branch.nil? || mirror.branch == 'master') ? '' : " branch '#{mirror.branch}'"
+          branch_message   = mirror.branch.nil? ? '' : " branch '#{mirror.branch}'"
           tag_message      = mirror.tag.nil? ? '' : " tag '#{mirror.tag}'"
           revision_message = options['revision'] ? " at #{display_revision(mirror, options['revision'])}" : ''
           msg "Adding mirror of '#{mirror.url}'#{branch_message}#{tag_message}#{revision_message}."

data/lib/braid/commands/diff.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class Diff < Command
@@ -35,7 +36,7 @@ module Braid
 
         # XXX: Warn if the user specifies file paths that are outside the
         # mirror?  Currently, they just won't match anything.
-        git.diff_to_stdout(*mirror.diff_args(options['git_diff_args']))
+        git.diff_to_stdout(mirror.diff_args(options['git_diff_args']))
 
         clear_remote(mirror, options)
       end

data/lib/braid/commands/push.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'fileutils'
 require 'tmpdir'
 
@@ -43,7 +44,8 @@ module Braid
         end
         clone_dir = Dir.tmpdir + "/braid_push.#{$$}"
         Dir.mkdir(clone_dir)
-        remote_url = git.remote_url(mirror.remote)
+        # TODO (typing): Remove this `T.must` somehow?
+        remote_url = T.must(git.remote_url(mirror.remote))
         if remote_url == mirror.cached_url
           remote_url = mirror.url
         elsif File.directory?(remote_url)
@@ -67,7 +69,7 @@ module Braid
           File.open('.git/objects/info/alternates', 'wb') { |f|
             f.puts(odb_paths)
           }
-          git.fetch(remote_url, mirror.remote_ref)
+          git.fetch(remote_url, [mirror.remote_ref])
           new_tree = git.make_tree_with_item(base_revision,
             mirror.remote_path || '', local_mirror_item)
           if git.require_version('2.27')
@@ -105,11 +107,11 @@ module Braid
           # Update HEAD the same way git.checkout(base_revision) would, but
           # don't populate the index or working tree (to save us the trouble of
           # emptying them again before the git.read_tree).
-          git.update_ref('--no-deref', 'HEAD', base_revision)
-          git.read_tree('-mu', new_tree)
+          git.update_ref(['--no-deref', 'HEAD', base_revision])
+          git.read_tree_um(new_tree)
           system('git commit -v')
           msg "Pushing changes to remote branch #{branch}."
-          git.push(remote_url, "HEAD:refs/heads/#{branch}")
+          git.push([remote_url, "HEAD:refs/heads/#{branch}"])
         end
         FileUtils.rm_r(clone_dir)
 

data/lib/braid/commands/remove.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class Remove < Command

data/lib/braid/commands/setup.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class Setup < Command

data/lib/braid/commands/status.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class Status < Command

data/lib/braid/commands/update.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class Update < Command

data/lib/braid/commands/upgrade_config.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Braid
   module Commands
     class UpgradeConfig < Command

data/lib/braid/main.rb

@@ -1,13 +1,24 @@
+# typed: true
+
 require 'braid'
 
 require 'rubygems'
 require 'main'
 
+# This is needed for `T` below to resolve to `Braid::T` when using the fake
+# Sorbet runtime.  TODO: Indent the contents and accept the large diff?
+module Braid
+
 Home = File.expand_path(ENV['HOME'] || '~')
 
 # mostly blantantly stolen from ara's punch script
 # main kicks ass!
-Main {
+T.unsafe(Main).run {
+  # `Main` is somewhat mind-bending and I'm unsure what the type of `self`
+  # actually is here, but whatever it is, we don't have a type declaration for
+  # it.
+  T.bind(self, T.untyped)
+
   description <<-TXT
     braid is a simple tool to help track git repositories inside a git repository.
 
@@ -20,7 +31,8 @@ Main {
   # The "main" library doesn't provide a way to do this??
   def check_no_extra_args!
     if @argv.length > 0
-      die 'Extra argument(s) passed to command.'
+      Braid::Command.handle_error(
+        Braid::BraidError.new('Extra argument(s) passed to command.'))
     end
   end
 
@@ -123,7 +135,7 @@ Main {
 
     mixin :optional_local_path, :option_verbose, :option_keep_remote
 
-    synopsis(Main::Usage.default_synopsis(self) + ' [-- git_diff_arg*]')
+    synopsis(T.unsafe(Main::Usage).default_synopsis(self) + ' [-- git_diff_arg*]')
 
     run {
       if @argv.length > 0 && @argv[0] == '--'
@@ -318,3 +330,5 @@ Main {
 
   run { help! }
 }
+
+end

data/lib/braid/mirror.rb

@@ -86,7 +86,7 @@ DESC
       raise NoTagAndBranch if options['tag'] && options['branch']
 
       tag = options['tag']
-      branch = options['branch'] || (tag.nil? ? 'master' : nil)
+      branch = options['branch']
 
       path = (options['path'] || extract_path_from_url(url, options['remote_path'])).sub(/\/$/, '')
       raise PathRequired unless path
@@ -107,7 +107,7 @@ DESC
       branch.nil? && tag.nil?
     end
 
-    sig {params(commit: String).returns(T::Boolean)}
+    sig {params(commit: Operations::Git::ObjectExpr).returns(T::Boolean)}
     def merged?(commit)
       # tip from spearce in #git:
       # `test z$(git merge-base A B) = z$(git rev-parse --verify A)`
@@ -115,9 +115,7 @@ DESC
       !!base_revision && git.merge_base(commit, base_revision) == commit
     end
 
-    # We'll probably call the return type something like
-    # Braid::Operations::Git::TreeItem.
-    sig {params(revision: String).returns(T.untyped)}
+    sig {params(revision: String).returns(Operations::Git::TreeItem)}
     def upstream_item_for_revision(revision)
       git.get_tree_item(revision, self.remote_path)
     end
@@ -211,16 +209,28 @@ DESC
       git.remote_url(remote) == cached_url
     end
 
-    sig {returns(String)}
+    sig {returns(Operations::Git::ObjectID)}
     def base_revision
-      # Avoid a Sorbet "unreachable code" error.
-      # TODO (typing): Is the revision expected to be non-nil nowadays?  Can we
-      # just remove the `inferred_revision` code path now?
-      nilable_revision = T.let(revision, T.nilable(String))
-      if nilable_revision
-        git.rev_parse(revision)
+      # TODO (typing): We think `revision` should always be non-nil here these
+      # days and we can completely drop the `inferred_revision` code, but we're
+      # waiting for a better time to actually make this runtime behavior change
+      # and accept any risk of breakage
+      # (https://github.com/cristibalan/braid/pull/105/files#r857150464).
+      #
+      # Temporary variable
+      # (https://sorbet.org/docs/flow-sensitive#limitations-of-flow-sensitivity)
+      revision1 = revision
+      if revision1
+        git.rev_parse(revision1)
       else
-        inferred_revision
+        # NOTE: Given that `inferred_revision` does appear to return nil on one
+        # code path, using this `T.must` and giving `base_revision` a
+        # non-nilable return type presents a theoretical risk of leading us to
+        # make changes to callers that break things at runtime.  But we judge
+        # this a lesser evil than making the return type nilable and changing
+        # all callers to type-check successfully with that when we hope to
+        # revert the change soon anyway.
+        T.must(inferred_revision)
       end
     end
 
@@ -310,7 +320,12 @@ DESC
 
     sig {returns(String)}
     def remote
-      "#{branch || tag || 'revision'}/braid/#{path}".gsub(/\/\./, '/_')
+      # Ensure that we replace any characters in the mirror path that might be
+      # problematic in a Git ref name.  Theoretically, this may introduce
+      # collisions between mirrors, but we don't expect that to be much of a
+      # problem because Braid doesn't keep remotes by default after a command
+      # exits.
+      "#{branch || tag || 'revision'}_braid_#{path}".gsub(/[^-A-Za-z0-9]/, '_')
     end
 
     private
@@ -322,8 +337,8 @@ DESC
 
     sig {returns(T.nilable(String))}
     def inferred_revision
-      local_commits = git.rev_list('HEAD', "-- #{path}").split("\n")
-      remote_hashes = git.rev_list("--pretty=format:\"%T\"", remote).split('commit ').map do |chunk|
+      local_commits = git.rev_list(['HEAD', "-- #{path}"]).split("\n")
+      remote_hashes = git.rev_list(["--pretty=format:%T", remote]).split('commit ').map do |chunk|
         chunk.split("\n", 2).map { |value| value.strip }
       end
       hash          = T.let(nil, T.nilable(String))

data/lib/braid/operations.rb

@@ -1,5 +1,8 @@
+# typed: strict
+
 require 'singleton'
 require 'rubygems'
+require 'shellwords'
 require 'tempfile'
 
 module Braid
@@ -7,45 +10,64 @@ module Braid
 
   module Operations
     class ShellExecutionError < BraidError
+      # TODO (typing): Should this be nilable?
+      sig {returns(T.nilable(String))}
       attr_reader :err, :out
 
+      sig {params(err: T.nilable(String), out: T.nilable(String)).void}
       def initialize(err = nil, out = nil)
         @err = err
         @out = out
       end
 
+      sig {returns(String)}
       def message
-        @err.to_s.split("\n").first
+        first_line = @err.to_s.split("\n").first
+        # Currently, first_line can be nil if @err was empty, but Sorbet thinks
+        # that the `message` method of an Exception should always return non-nil
+        # (although override checking isn't enforced as of this writing), so
+        # handle nil here.  This seems ad-hoc but better than putting in a
+        # `T.must` that we know has a risk of being wrong.  Hopefully this will
+        # be fixed better in https://github.com/cristibalan/braid/issues/90.
+        first_line.nil? ? '' : first_line
       end
     end
     class VersionTooLow < BraidError
+      sig {params(command: String, version: String, required: String).void}
       def initialize(command, version, required)
         @command  = command
-        @version  = version.to_s.split("\n").first
+        # TODO (typing): Probably should not be nilable
+        @version  = T.let(version.to_s.split("\n").first, T.nilable(String))
         @required = required
       end
 
+      sig {returns(String)}
       def message
         "#{@command} version too low: #{@version}. #{@required} needed."
       end
     end
     class UnknownRevision < BraidError
+      sig {returns(String)}
       def message
         "unknown revision: #{super}"
       end
     end
     class LocalChangesPresent < BraidError
+      sig {returns(String)}
       def message
         'local changes are present'
       end
     end
     class MergeError < BraidError
+      sig {returns(String)}
       attr_reader :conflicts_text
 
+      sig {params(conflicts_text: String).void}
       def initialize(conflicts_text)
         @conflicts_text = conflicts_text
       end
 
+      sig {returns(String)}
       def message
         'could not merge'
       end
@@ -53,18 +75,24 @@ module Braid
 
     # The command proxy is meant to encapsulate commands such as git, that work with subcommands.
     class Proxy
+      extend T::Sig
       include Singleton
 
-      def self.command;
-        name.split('::').last.downcase;
+      # TODO (typing): We could make this method abstract if our fake Sorbet
+      # runtime supported abstract methods.
+      sig {returns(String)}
+      def self.command
+        raise InternalError, 'Proxy.command not overridden'
       end
 
       # hax!
+      sig {returns(String)}
       def version
-        _, out, _ = exec!("#{self.class.command} --version")
+        _, out, _ = exec!([self.class.command, '--version'])
         out.sub(/^.* version/, '').strip.sub(/ .*$/, '').strip
       end
 
+      sig {params(required: String).returns(T::Boolean)}
       def require_version(required)
         # Gem::Version is intended for Ruby gem versions, but various web sites
         # suggest it as a convenient way of comparing version strings in
@@ -73,77 +101,115 @@ module Braid
         Gem::Version.new(version) >= Gem::Version.new(required)
       end
 
+      sig {params(required: String).void}
       def require_version!(required)
         require_version(required) || raise(VersionTooLow.new(self.class.command, version, required))
       end
 
       private
 
+      sig {params(name: String).returns(T::Array[String])}
       def command(name)
         # stub
-        name
+        [name]
       end
 
-      def invoke(arg, *args)
-        exec!("#{command(arg)} #{args.join(' ')}".strip)[1].strip # return stdout
+      sig {params(arg: String, args: T::Array[String]).returns(String)}
+      def invoke(arg, args)
+        exec!(command(arg) + args)[1].strip # return stdout
       end
 
-      def method_missing(name, *args)
-        invoke(name, *args)
-      end
+      # Some of the unit tests want to mock out `exec`, but they have no way to
+      # construct a real Process::Status and thus use an integer instead.  We
+      # have to accommodate this in the type annotation to avoid runtime type
+      # check failures during the tests.  In normal use of Braid, this will
+      # always be a real Process::Status.  Fortunately, allowing Integer doesn't
+      # seem to cause any other problems right now.
+      ProcessStatusOrInteger = T.type_alias { T.any(Process::Status, Integer) }
 
+      sig {params(cmd: T::Array[String]).returns([ProcessStatusOrInteger, String, String])}
       def exec(cmd)
-        cmd.strip!
-
         Operations::with_modified_environment({'LANG' => 'C'}) do
           log(cmd)
-          out, err, status = Open3.capture3(cmd)
+          # The special `[cmd[0], cmd[0]]` syntax ensures that `cmd[0]` is
+          # interpreted as the path of the executable and not a shell command
+          # even if `cmd` has only one element. See the documentation:
+          # https://ruby-doc.org/core-3.1.2/Process.html#method-c-spawn.
+          # Granted, this shouldn't matter for Braid for two reasons: (1)
+          # `cmd[0]` is always "git", which doesn't contain any shell special
+          # characters, and (2) `cmd` always has at least one additional
+          # argument (the Git subcommand). However, it's still nice to make our
+          # intent clear.
+          out, err, status = T.unsafe(Open3).capture3([cmd[0], cmd[0]], *cmd[1..])
           [status, out, err]
         end
       end
 
+      sig {params(cmd: T::Array[String]).returns([ProcessStatusOrInteger, String, String])}
       def exec!(cmd)
         status, out, err = exec(cmd)
         raise ShellExecutionError.new(err, out) unless status == 0
         [status, out, err]
       end
 
+      sig {params(cmd: T::Array[String]).returns(ProcessStatusOrInteger)}
       def system(cmd)
-        cmd.strip!
-
         # Without this, "braid diff" output came out in the wrong order on Windows.
         $stdout.flush
         $stderr.flush
         Operations::with_modified_environment({'LANG' => 'C'}) do
-          Kernel.system(cmd)
+          # See the comment in `exec` about the `[cmd[0], cmd[0]]` syntax.
+          T.unsafe(Kernel).system([cmd[0], cmd[0]], *cmd[1..])
           return $?
         end
       end
 
+      sig {params(str: String).void}
       def msg(str)
         puts "Braid: #{str}"
       end
 
+      sig {params(cmd: T::Array[String]).void}
       def log(cmd)
-        msg "Executing `#{cmd}` in #{Dir.pwd}" if verbose?
+        # Note: `Shellwords.shelljoin` follows Bourne shell quoting rules, as
+        # its documentation states.  This may not be what a Windows user
+        # expects, but it's not worth the trouble to try to find a library that
+        # produces something better on Windows, especially because it's unclear
+        # which of Windows's several different quoted formats we would use
+        # (e.g., CommandLineToArgvW, cmd.exe, or PowerShell).  The most
+        # important thing is to use _some_ unambiguous representation.
+        msg "Executing `#{Shellwords.shelljoin(cmd)}` in #{Dir.pwd}" if verbose?
       end
 
+      sig {returns(T::Boolean)}
       def verbose?
         Braid.verbose
       end
     end
 
     class Git < Proxy
+
+      sig {returns(String)}
+      def self.command
+        'git'
+      end
+
+      # A string representing a Git object ID (i.e., hash).  This type alias is
+      # used as documentation and is not enforced, so there's a risk that we
+      # mistakenly mark something as an ObjectID when it can actually be a
+      # String that is not an ObjectID.
+      ObjectID = T.type_alias { String }
+
+      # A string containing an expression that can be evaluated to an object ID
+      # by `git rev-parse`.  Ditto the remark about lack of enforcement.
+      ObjectExpr = T.type_alias { String } 
+
       # Get the physical path to a file in the git repository (e.g.,
       # 'MERGE_MSG'), taking into account worktree configuration.  The returned
       # path may be absolute or relative to the current working directory.
+      sig {params(path: String).returns(String)}
       def repo_file_path(path)
-        if require_version('2.5')  # support for --git-path
-          invoke(:rev_parse, '--git-path', path)
-        else
-          # Git < 2.5 doesn't support linked worktrees anyway.
-          File.join(invoke(:rev_parse, '--git-dir'), path)
-        end
+        invoke('rev-parse', ['--git-path', path])
       end
 
       # If the current directory is not inside a git repository at all, this
@@ -151,8 +217,9 @@ module Braid
       # propagated as a ShellExecutionError.  is_inside_worktree can return
       # false when inside a bare repository and in certain other rare cases such
       # as when the GIT_WORK_TREE environment variable is set.
+      sig {returns(T::Boolean)}
       def is_inside_worktree
-        invoke(:rev_parse, '--is-inside-work-tree') == 'true'
+        invoke('rev-parse', ['--is-inside-work-tree']) == 'true'
       end
 
       # Get the prefix of the current directory relative to the worktree.  Empty
@@ -160,21 +227,23 @@ module Braid
       # In some cases in which the current directory is not inside a worktree at
       # all, this will successfully return an empty string, so it may be
       # desirable to check is_inside_worktree first.
+      sig {returns(String)}
       def relative_working_dir
-        invoke(:rev_parse, '--show-prefix')
+        invoke('rev-parse', ['--show-prefix'])
       end
 
-      def commit(message, *args)
-        cmd = 'git commit --no-verify'
+      sig {params(message: T.nilable(String), args: T::Array[String]).returns(T::Boolean)}
+      def commit(message, args = [])
+        cmd = ['git', 'commit', '--no-verify']
         message_file = nil
         if message # allow nil
           message_file = Tempfile.new('braid_commit')
           message_file.print("Braid: #{message}")
           message_file.flush
           message_file.close
-          cmd << " -F #{message_file.path}"
+          cmd += ['-F', T.must(message_file.path)]
         end
-        cmd << " #{args.join(' ')}" unless args.empty?
+        cmd += args
         status, out, err = exec(cmd)
         message_file.unlink if message_file
 
@@ -187,50 +256,55 @@ module Braid
         end
       end
 
-      def fetch(remote = nil, *args)
-        args.unshift "-n #{remote}" if remote
-        exec!("git fetch #{args.join(' ')}")
-      end
-
-      def checkout(treeish)
-        invoke(:checkout, treeish)
-        true
+      sig {params(remote: T.nilable(String), args: T::Array[String]).void}
+      def fetch(remote = nil, args = [])
+        args = ['-n', remote] + args if remote
+        exec!(['git', 'fetch'] + args)
       end
 
       # Returns the base commit or nil.
+      sig {params(target: ObjectExpr, source: ObjectExpr).returns(T.nilable(ObjectID))}
       def merge_base(target, source)
-        invoke(:merge_base, target, source)
+        invoke('merge-base', [target, source])
       rescue ShellExecutionError
         nil
       end
 
-      def rev_parse(opt)
-        invoke(:rev_parse, opt)
+      sig {params(expr: ObjectExpr).returns(ObjectID)}
+      def rev_parse(expr)
+        invoke('rev-parse', [expr])
       rescue ShellExecutionError
-        raise UnknownRevision, opt
+        raise UnknownRevision, expr
       end
 
       # Implies tracking.
+      #
+      # TODO (typing): Remove the return value if we're confident that nothing
+      # uses it, here and in similar cases.
+      sig {params(remote: String, path: String).returns(TrueClass)}
       def remote_add(remote, path)
-        invoke(:remote, 'add', remote, path)
+        invoke('remote', ['add', remote, path])
         true
       end
 
+      sig {params(remote: String).returns(TrueClass)}
       def remote_rm(remote)
-        invoke(:remote, 'rm', remote)
+        invoke('remote', ['rm', remote])
         true
       end
 
       # Checks git remotes.
+      sig {params(remote: String).returns(T.nilable(String))}
       def remote_url(remote)
         key = "remote.#{remote}.url"
-        invoke(:config, key)
+        invoke('config', [key])
       rescue ShellExecutionError
         nil
       end
 
+      sig {params(target: ObjectExpr).returns(TrueClass)}
       def reset_hard(target)
-        invoke(:reset, '--hard', target)
+        invoke('reset', ['--hard', target])
         true
       end
 
@@ -242,41 +316,59 @@ module Braid
       # 'recursive' part (i.e., merge of bases) does not come into play and only
       # the trees matter.  But for some reason, Git's smartest tree merge
       # algorithm is only available via the 'recursive' strategy.
+      sig {params(base_treeish: ObjectExpr, local_treeish: ObjectExpr, remote_treeish: ObjectExpr).returns(TrueClass)}
       def merge_trees(base_treeish, local_treeish, remote_treeish)
-        invoke(:merge_recursive, base_treeish, "-- #{local_treeish} #{remote_treeish}")
+        invoke('merge-recursive', [base_treeish, '--', local_treeish, remote_treeish])
         true
       rescue ShellExecutionError => error
         # 'CONFLICT' messages go to stdout.
         raise MergeError, error.out
       end
 
+      sig {params(prefix: String).returns(String)}
       def read_ls_files(prefix)
-        invoke('ls-files', prefix)
+        invoke('ls-files', [prefix])
       end
 
       class BlobWithMode
+        extend T::Sig
+        sig {params(hash: ObjectID, mode: String).void}
         def initialize(hash, mode)
           @hash = hash
           @mode = mode
         end
-        attr_reader :hash, :mode
+        sig {returns(ObjectID)}
+        attr_reader :hash
+        sig {returns(String)}
+        attr_reader :mode
       end
       # Allow the class to be referenced as `git.BlobWithMode`.
+      sig {returns(T.class_of(BlobWithMode))}
       def BlobWithMode
         Git::BlobWithMode
       end
+      # An ObjectID used as a TreeItem represents a tree.
+      TreeItem = T.type_alias { T.any(ObjectID, BlobWithMode) }
 
       # Get the item at the given path in the given tree.  If it's a tree, just
       # return its hash; if it's a blob, return a BlobWithMode object.  (This is
       # how we remember the mode for single-file mirrors.)
+      # TODO (typing): Should `path` be nilable?
+      sig {params(tree: ObjectExpr, path: T.nilable(String)).returns(TreeItem)}
       def get_tree_item(tree, path)
         if path.nil? || path == ''
           tree
         else
-          m = /^([^ ]*) ([^ ]*) ([^\t]*)\t.*$/.match(invoke(:ls_tree, tree, path))
-          mode = m[1]
-          type = m[2]
-          hash = m[3]
+          m = /^([^ ]*) ([^ ]*) ([^\t]*)\t.*$/.match(invoke('ls-tree', [tree, path]))
+          if m.nil?
+            # This can happen if the user runs `braid add` with a `--path` that
+            # doesn't exist.  TODO: Make the error message more user-friendly in
+            # that case.
+            raise ShellExecutionError, 'No tree item exists at the given path'
+          end
+          mode = T.must(m[1])
+          type = T.must(m[2])
+          hash = T.must(m[3])
           if type == 'tree'
             hash
           elsif type == 'blob'
@@ -291,37 +383,47 @@ module Braid
       # path.  If update_worktree is true, then update the worktree, otherwise
       # disregard the state of the worktree (most useful with a temporary index
       # file).
+      sig {params(item: TreeItem, path: String, update_worktree: T::Boolean).void}
       def add_item_to_index(item, path, update_worktree)
         if item.is_a?(BlobWithMode)
-          # Our minimum git version is 1.6.0 and the new --cacheinfo syntax
-          # wasn't added until 2.0.0.
-          invoke(:update_index, '--add', '--cacheinfo', item.mode, item.hash, path)
+          invoke('update-index', ['--add', '--cacheinfo', "#{item.mode},#{item.hash},#{path}"])
           if update_worktree
             # XXX If this fails, we've already updated the index.
-            invoke(:checkout_index, path)
+            invoke('checkout-index', [path])
           end
         else
           # According to
           # https://lore.kernel.org/git/e48a281a4d3db0a04c0609fcb8658e4fcc797210.1646166271.git.gitgitgadget@gmail.com/,
           # `--prefix=` is valid if the path is empty.
-          invoke(:read_tree, "--prefix=#{path}", update_worktree ? '-u' : '-i', item)
+          invoke('read-tree', ["--prefix=#{path}", update_worktree ? '-u' : '-i', item])
         end
       end
 
       # Read tree into the root of the index.  This may not be the preferred way
       # to do it, but it seems to work.
+      sig {params(treeish: ObjectExpr).void}
       def read_tree_im(treeish)
-        invoke(:read_tree, '-im', treeish)
-        true
+        invoke('read-tree', ['-im', treeish])
+      end
+
+      sig {params(treeish: ObjectExpr).void}
+      def read_tree_um(treeish)
+        invoke('read-tree', ['-um', treeish])
       end
 
       # Write a tree object for the current index and return its ID.
+      sig {returns(ObjectID)}
       def write_tree
-        invoke(:write_tree)
+        invoke('write-tree', [])
       end
 
       # Execute a block using a temporary git index file, initially empty.
-      def with_temporary_index
+      sig {
+        type_parameters(:R).params(
+          blk: T.proc.returns(T.type_parameter(:R))
+        ).returns(T.type_parameter(:R))
+      }
+      def with_temporary_index(&blk)
         Dir.mktmpdir('braid_index') do |dir|
           Operations::with_modified_environment(
             {'GIT_INDEX_FILE' => File.join(dir, 'index')}) do
@@ -330,6 +432,7 @@ module Braid
         end
       end
 
+      sig {params(main_content: T.nilable(ObjectExpr), item_path: String, item: TreeItem).returns(ObjectID)}
       def make_tree_with_item(main_content, item_path, item)
         with_temporary_index do
           # If item_path is '', then rm_r_cached will fail.  But in that case,
@@ -344,103 +447,161 @@ module Braid
         end
       end
 
+      sig {params(args: T::Array[String]).returns(T.nilable(String))}
       def config(args)
-        invoke(:config, args) rescue nil
+        invoke('config', args) rescue nil
       end
 
+      sig {params(path: String).void}
+      def add(path)
+        invoke('add', [path])
+      end
+
+      sig {params(path: String).void}
+      def rm(path)
+        invoke('rm', [path])
+      end
+
+      sig {params(path: String).returns(TrueClass)}
       def rm_r(path)
-        invoke(:rm, '-r', path)
+        invoke('rm', ['-r', path])
         true
       end
 
       # Remove from index only.
+      sig {params(path: String).returns(TrueClass)}
       def rm_r_cached(path)
-        invoke(:rm, '-r', '--cached', path)
+        invoke('rm', ['-r', '--cached', path])
         true
       end
 
+      sig {params(path: String, treeish: ObjectExpr).returns(ObjectID)}
       def tree_hash(path, treeish = 'HEAD')
-        out = invoke(:ls_tree, treeish, '-d', path)
-        out.split[2]
+        out = invoke('ls-tree', [treeish, '-d', path])
+        T.must(out.split[2])
+      end
+
+      sig {params(args: T::Array[String]).returns(String)}
+      def diff(args)
+        invoke('diff', args)
       end
 
-      def diff_to_stdout(*args)
+      sig {params(args: T::Array[String]).returns(ProcessStatusOrInteger)}
+      def diff_to_stdout(args)
         # For now, ignore the exit code.  It can be 141 (SIGPIPE) if the user
         # quits the pager before reading all the output.
-        system("git diff #{args.join(' ')}")
+        system(['git', 'diff'] + args)
       end
 
+      sig {returns(T::Boolean)}
       def status_clean?
-        _, out, _ = exec('git status')
+        _, out, _ = exec(['git', 'status'])
         !out.split("\n").grep(/nothing to commit/).empty?
       end
 
+      sig {void}
       def ensure_clean!
         status_clean? || raise(LocalChangesPresent)
       end
 
+      sig {returns(ObjectID)}
       def head
         rev_parse('HEAD')
       end
 
-      def branch
-        _, out, _ = exec!("git branch | grep '*'")
-        out[2..-1]
+      sig {void}
+      def init
+        invoke('init', [])
+      end
+
+      sig {params(args: T::Array[String]).void}
+      def clone(args)
+        invoke('clone', args)
+      end
+
+      # Wrappers for Git commands that were called via `method_missing` before
+      # the move to static typing but for which the existing calls don't follow
+      # a clear enough pattern around which we could design a narrower API than
+      # forwarding an arbitrary argument list.  We may narrow the API in the
+      # future if it becomes clear what it should be.
+
+      sig {params(args: T::Array[String]).returns(String)}
+      def rev_list(args)
+        invoke('rev-list', args)
+      end
+
+      sig {params(args: T::Array[String]).void}
+      def update_ref(args)
+        invoke('update-ref', args)
+      end
+
+      sig {params(args: T::Array[String]).void}
+      def push(args)
+        invoke('push', args)
       end
 
-      def clone(*args)
-        # overrides builtin
-        invoke(:clone, *args)
+      sig {params(args: T::Array[String]).returns(String)}
+      def ls_remote(args)
+        invoke('ls-remote', args)
       end
 
       private
 
+      sig {params(name: String).returns(T::Array[String])}
       def command(name)
-        "#{self.class.command} #{name.to_s.gsub('_', '-')}"
+        [self.class.command, name]
       end
     end
 
     class GitCache
+      extend T::Sig
       include Singleton
 
+      sig {params(url: String).void}
       def fetch(url)
         dir = path(url)
 
         # remove local cache if it was created with --no-checkout
-        if File.exists?("#{dir}/.git")
+        if File.exist?("#{dir}/.git")
           FileUtils.rm_r(dir)
         end
 
-        if File.exists?(dir)
+        if File.exist?(dir)
           Dir.chdir(dir) do
             git.fetch
           end
         else
           FileUtils.mkdir_p(local_cache_dir)
-          git.clone('--mirror', url, dir)
+          git.clone(['--mirror', url, dir])
         end
       end
 
+      sig {params(url: String).returns(String)}
       def path(url)
         File.join(local_cache_dir, url.gsub(/[\/:@]/, '_'))
       end
 
       private
 
+      sig {returns(String)}
       def local_cache_dir
         Braid.local_cache_dir
       end
 
+      sig {returns(Git)}
       def git
         Git.instance
       end
     end
 
     module VersionControl
+      extend T::Sig
+      sig {returns(Git)}
       def git
         Git.instance
       end
 
+      sig {returns(GitCache)}
       def git_cache
         GitCache.instance
       end

data/lib/braid/sorbet/fake_runtime.rb

@@ -36,6 +36,10 @@ module Braid
     def self.must(value)
       value
     end
+    def self.unsafe(value)
+      value
+    end
+    def self.bind(value, type); end
 
     class FakeType
       include Singleton
@@ -52,6 +56,12 @@ module Braid
     def self.untyped
       FAKE_TYPE
     end
+    def self.noreturn
+      FAKE_TYPE
+    end
+    def self.any(*types)
+      FAKE_TYPE
+    end
     Boolean = FAKE_TYPE
     module Array
       def self.[](type)

data/lib/braid/version.rb

@@ -1,3 +1,6 @@
+# Ditto the comment in `check_gem.rb` regarding the `typed` sigil.
+# typed: false
+
 module Braid
-  VERSION = '1.1.7'.freeze
+  VERSION = '1.1.9'.freeze
 end

data/lib/braid.rb

@@ -12,14 +12,13 @@ module Braid
   # See the background in the "Supported environments" section of README.md.
   #
   # The newest Git feature that Braid is currently known to rely on is
-  # `receive.denyCurrentBranch = updateInstead` (in
-  # spec/integration/push_spec.rb), which was added in Git 2.3.0 (in 2015).  It
+  # `git ls-remote --symref`, which was added in Git 2.8.0 (in 2016).  It
   # doesn't seem worth even a small amount of work to remove that dependency and
   # support even older versions of Git.  So set that as the declared requirement
   # for now.  In general, a reasonable approach might be to try to support the
   # oldest version of Git in current "long-term support" versions of popular OS
   # distributions.
-  REQUIRED_GIT_VERSION = '2.3.0'
+  REQUIRED_GIT_VERSION = '2.8.0'
 
   @verbose = T.let(false, T::Boolean)
 

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: braid
 version: !ruby/object:Gem::Version
-  version: 1.1.7
+  version: 1.1.9
 platform: ruby
 authors:
 - Cristi Balan
 - Norbert Crombach
 - Peter Donald
 - Matt McCutchen
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-15 00:00:00.000000000 Z
+date: 2023-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: main
@@ -97,6 +97,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A simple tool for tracking vendor branches in git.
 email: evil@che.lu norbert.crombach@primetheory.org peter@realityforge.org matt@mattmccutchen.net
 executables:
@@ -128,7 +142,7 @@ files:
 homepage: https://github.com/cristibalan/braid
 licenses: []
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options:
 - "--line-numbers"
 - "--inline-source"
@@ -148,8 +162,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 3.1.4
+signing_key: 
 specification_version: 4
 summary: A simple tool for tracking vendor branches in git.
 test_files: []