braid 1.1.5 → 1.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820284531c81fc3d920345ddca21afa6cb6f49489aa088c2eb6b3233923069e9
-  data.tar.gz: ee5eb584e64c6426e77905bc1d8ac7d1622620665749546bf142c424dacf027e
+  metadata.gz: 6efac3d863ec38976f90032c012ebe9acca8911a9316608d7dfe704cc0d8925b
+  data.tar.gz: 5c5c8870bbf0702767234ee5b467324c7c25914ed3de06ac67ef903f87ca4ee7
 SHA512:
-  metadata.gz: 71b869dfd6f57e8d64238b7d09761415d807572cd2d2b71e8f0d0a3fb48d759af2269f0ba13a946142408981b8edb3d84c8f00cca51ed1542fcf0a785e5c38f4
-  data.tar.gz: fe09b15e8062fab7aa8389dddc9bae1c4f684e583bed5ac3105970fe7ad6d809b5af9583cf6c970563a8471317a78cfac505522f3402403b7d547aba087a613c
+  metadata.gz: dcb55a781668a47cdae99c5e013844b3234c7edcaeec21d71f64174dfc6ae3339acf89083b3256244fd430bdf035285d44cd9244d2abd6808b97f1c3c0be41cf
+  data.tar.gz: b8143594481cb94c3ca8c099e02c4c231be84e4a742b5e2047a7e79c82ea0e47c1b8e1ece68719130870aa613f5bca20182eb85e62f1d45a8bca210c0e163f80

data/exe/braid

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+# I haven't found a clean way to get Sorbet to check this file since the name
+# doesn't end in `.rb`.  (If I add `--file bin/braid` to `sorbet/config`, then
+# the Sorbet language server doesn't support using Watchman.)  So move all the
+# interesting code to `lib/braid/main.rb` and leave this as a launcher that
+# doesn't have any code worth type checking. ~ Matt 2022-04-02
+
+require_relative '../lib/braid/check_gem'
+
+require 'braid/main'

data/lib/braid/check_gem.rb

@@ -0,0 +1,65 @@
+# 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
+# gemspec or Gemfile, as applicable).  This currently applies to the following
+# entry points:
+#
+# - The Braid CLI launcher: `exe/braid`
+# - The Braid test suite under `spec`
+# - The Rakefile: Has a target to run the Sorbet type checker and wants the
+#   correct version for the current version of Braid.
+#
+# If these entry points are invoked without first activating the correct gems,
+# then other globally installed versions might be used by default, leading to
+# unintended behavior.  So we have each of these entry points check that a Braid
+# gem is active in the current Ruby interpreter _and_ the entry point is part of
+# that same Braid gem.  If so, we can assume that the correct versions of
+# dependencies are active as well.
+#
+# To implement the check, the entry point file loads its corresponding copy of
+# check_gem.rb via `require_relative`, and that copy of check_gem.rb checks that
+# it is part of the active Braid gem.  Note that loading check_gem.rb via
+# `require 'lib/braid/check_gem'` would defeat the purpose, since it would
+# activate whatever Braid gem is visible and then check that that gem's copy of
+# check_gem.rb is part of the active Braid gem (which it would always be), not
+# whether the _caller_ is part of the active Braid gem.
+#
+# Common means of activating the correct gems before invoking an entry point
+# include:
+#
+# - Bundler: Used when developing Braid itself and possibly by some projects
+#   that use Braid.  It modifies the environment so that every Ruby subprocess
+#   activates the gems from the Gemfile.lock.
+# - A wrapper for `exe/braid` generated by `gem install --wrappers`.
+#
+# Note that we don't have every `.rb` file that is part of Braid load
+# check_gem.rb: that would be too invasive and only helps in the case where a
+# user manually added Braid's `lib` dir to the load path, which is a mistake
+# that a reasonable user is much less likely to make than just running an entry
+# point without the proper setup.
+#
+# TODO: Is there a more standard way to do this check?  One would think it would
+# be potentially applicable to any Ruby project, though maybe most don't care as
+# much as we do about catching the problem up front.
+
+braid_spec = Gem.loaded_specs['braid']
+if braid_spec.nil? || __FILE__ != braid_spec.gem_dir + '/lib/braid/check_gem.rb'
+  STDERR.puts <<-MSG
+Error: The RubyGems environment is not set up correctly for Braid.
+- If you're using a copy of Braid installed globally via 'gem install' or
+  similar, use the 'braid' wrapper script (which is typically installed at a
+  location like ~/.gem/ruby/bin/braid depending on your environment) instead of
+  running 'exe/braid' directly.
+- If you're using a copy of Braid managed by Bundler (including when developing
+  Braid itself), prepend 'bundle exec' to your command or use a binstub
+  generated by 'bundle binstubs'.
+MSG
+  exit(1)
+end

data/lib/braid/command.rb

@@ -1,5 +1,8 @@
+# typed: true
 module Braid
   class Command
+    extend T::Sig
+
     class InvalidRevision < BraidError
     end
 
@@ -14,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}"
@@ -23,10 +31,12 @@ module Braid
       exit(1)
     end
 
+    sig {params(str: String).void}
     def self.msg(str)
       puts "Braid: #{str}"
     end
 
+    sig {params(str: String).void}
     def msg(str)
       self.class.msg(str)
     end
@@ -35,16 +45,19 @@ module Braid
       @config ||= Config.new({'mode' => config_mode})
     end
 
+    sig {returns(T::Boolean)}
     def verbose?
       Braid.verbose
     end
 
+    sig {returns(T::Boolean)}
     def force?
       Braid.force
     end
 
     private
 
+    sig {returns(Config::ConfigMode)}
     def config_mode
       Config::MODE_MAY_WRITE
     end
@@ -63,14 +76,17 @@ module Braid
       git.remote_rm(mirror.remote) unless options['keep']
     end
 
+    sig {returns(T::Boolean)}
     def use_local_cache?
       Braid.use_local_cache
     end
 
+    sig {void}
     def self.verify_git_version!
       git.require_version!(REQUIRED_GIT_VERSION)
     end
 
+    sig {void}
     def self.check_working_dir!
       # If we aren't in a git repository at all, git.is_inside_worktree will
       # propagate a "fatal: Not a git repository" ShellException.
@@ -82,6 +98,7 @@ module Braid
       end
     end
 
+    sig {void}
     def bail_on_local_changes!
       git.ensure_clean!
     end
@@ -100,6 +117,7 @@ module Braid
       end
     end
 
+    sig {void}
     def add_config_file
       git.rm(OLD_CONFIG_FILE) if File.exist?(OLD_CONFIG_FILE)
       git.add(CONFIG_FILE)

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'
 

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/config.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'yaml'
 require 'json'
 require 'yaml/store'
@@ -48,6 +49,10 @@ require 'yaml/store'
 
 module Braid
   class Config
+    extend T::Sig
+
+    # TODO (typing): Migrate to T::Enum?
+    ConfigMode = T.type_alias { Integer }
 
     MODE_UPGRADE = 1
     MODE_READ_ONLY = 2
@@ -56,11 +61,13 @@ module Braid
     CURRENT_CONFIG_VERSION = 1
 
     class PathAlreadyInUse < BraidError
+      sig {returns(String)}
       def message
         "path already in use: #{super}"
       end
     end
     class MirrorDoesNotExist < BraidError
+      sig {returns(String)}
       def message
         "mirror does not exist: #{super}"
       end
@@ -70,9 +77,15 @@ module Braid
     end
 
     # For upgrade-config command only.  XXX: Ideally would be immutable.
-    attr_reader :config_version, :config_existed, :breaking_change_descs
+    sig {returns(Integer)}
+    attr_reader :config_version
+    sig {returns(T::Boolean)}
+    attr_reader :config_existed
+    sig {returns(T::Array[String])}
+    attr_reader :breaking_change_descs
 
     # options: config_file, old_config_files, mode
+    sig {params(options: T.untyped).void}
     def initialize(options = {})
       @config_file     = options['config_file']      || CONFIG_FILE
       old_config_files = options['old_config_files'] || [OLD_CONFIG_FILE]
@@ -150,6 +163,7 @@ MSG
 
     end
 
+    sig {params(url: String, options: T.untyped).returns(Mirror)}
     def add_from_options(url, options)
       mirror = Mirror.new_from_options(url, options)
 
@@ -157,33 +171,39 @@ MSG
       mirror
     end
 
+    sig {returns(T::Array[Mirror])}
     def mirrors
       @db.keys
     end
 
+    sig {params(path: String).returns(T.nilable(Mirror))}
     def get(path)
       key = path.to_s.sub(/\/$/, '')
       attributes = @db[key]
       attributes ? Mirror.new(path, attributes) : nil
     end
 
+    sig {params(path: String).returns(Mirror)}
     def get!(path)
       mirror = get(path)
       raise MirrorDoesNotExist, path unless mirror
       mirror
     end
 
+    sig {params(mirror: Mirror).void}
     def add(mirror)
       raise PathAlreadyInUse, mirror.path if get(mirror.path)
       write_mirror(mirror)
       write_db
     end
 
+    sig {params(mirror: Mirror).void}
     def remove(mirror)
       @db.delete(mirror.path)
       write_db
     end
 
+    sig {params(mirror: Mirror).void}
     def update(mirror)
       raise MirrorDoesNotExist, mirror.path unless get(mirror.path)
       write_mirror(mirror)
@@ -191,6 +211,7 @@ MSG
     end
 
     # Public for upgrade-config command only.
+    sig {void}
     def write_db
       new_db = {}
       @db.keys.sort.each do |key|
@@ -211,11 +232,12 @@ MSG
 
     private
 
+    sig {params(config_file: String, old_config_files: T::Array[String]).returns(T.untyped)}
     def load_config(config_file, old_config_files)
       (old_config_files + [config_file]).each do |file|
         next unless File.exist?(file)
         begin
-          store = YAML::Store.new(file)
+          store = T.let(YAML::Store, T.untyped).new(file)
           data = {}
           store.transaction(true) do
             store.roots.each do |path|
@@ -228,15 +250,17 @@ MSG
           return data if data
         end
       end
-      return nil
+      nil
     end
 
+    sig {params(mirror: Mirror).void}
     def write_mirror(mirror)
       @db[mirror.path] = clean_attributes(mirror.attributes)
     end
 
+    sig {params(hash: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped])}
     def clean_attributes(hash)
-      hash.reject { |k, v| v.nil? }
+      hash.reject { |_, v| v.nil? }
     end
   end
 end

data/{bin/braid → lib/braid/main.rb}

@@ -1,28 +1,24 @@
-#!/usr/bin/env ruby
+# typed: true
 
-# Duplicated from Braid::Command.run. :(
-def die(msg)
-  puts "Braid: Error: #{msg}"
-  exit(1)
-end
-
-# If we assume Ruby >= 2.0, we can use __dir__.
-libdir = File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
-unless File.exists?(libdir)
-  # Don't silently fall back to a different globally installed copy of Braid!
-  die "Cannot find Braid's 'lib' directory."
-end
-$LOAD_PATH.unshift(libdir)
 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.
 
@@ -35,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
 
@@ -138,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] == '--'
@@ -333,3 +330,5 @@ Main {
 
   run { help! }
 }
+
+end