braid 1.0.22 → 1.1.0

data/lib/braid/commands/update.rb

@@ -56,8 +56,6 @@ module Braid
         rescue InvalidRevision
           # Ignored as it means the revision matches expected
         end
-        target_revision = determine_target_revision(mirror, new_revision)
-        current_revision = determine_target_revision(mirror, mirror.base_revision)
 
         from_desc =
           original_tag ? "tag '#{original_tag}'" :
@@ -77,7 +75,7 @@ module Braid
 
         if !switching &&
           (
-            (options['revision'] && was_locked && target_revision == current_revision) ||
+            (options['revision'] && was_locked && new_revision == mirror.base_revision) ||
             (options['revision'].nil? && !was_locked && mirror.merged?(git.rev_parse(new_revision)))
           )
           msg "Mirror '#{mirror.path}' is already up to date."
@@ -93,11 +91,13 @@ module Braid
         in_error = false
         begin
           local_hash = git.rev_parse('HEAD')
-          base_hash = git.make_tree_with_subtree('HEAD', mirror.path, mirror.versioned_path(base_revision))
-          remote_hash = git.make_tree_with_subtree('HEAD', mirror.path, target_revision)
+          base_hash = git.make_tree_with_item('HEAD', mirror.path,
+            mirror.upstream_item_for_revision(base_revision))
+          remote_hash = git.make_tree_with_item('HEAD', mirror.path,
+            mirror.upstream_item_for_revision(new_revision))
           Operations::with_modified_environment({
             "GITHEAD_#{local_hash}" => 'HEAD',
-            "GITHEAD_#{remote_hash}" => target_revision
+            "GITHEAD_#{remote_hash}" => new_revision
           }) do
             git.merge_trees(base_hash, local_hash, remote_hash)
           end
@@ -121,15 +121,6 @@ module Braid
         msg "Updated mirror to #{display_revision(mirror)}."
         clear_remote(mirror, options)
       end
-
-      def generate_tree_hash(mirror, revision)
-        git.with_temporary_index do
-          git.read_tree_im('HEAD')
-          git.rm_r_cached(mirror.path)
-          git.read_tree_prefix_i(revision, mirror.path)
-          git.write_tree
-        end
-      end
     end
   end
 end

data/lib/braid/commands/upgrade_config.rb

@@ -0,0 +1,56 @@
+module Braid
+  module Commands
+    class UpgradeConfig < Command
+      def config_mode
+        Config::MODE_UPGRADE
+      end
+
+      def run(options)
+        # Config loading in MODE_UPGRADE will bail out only if the config
+        # version is too new.
+
+        if !config.config_existed
+          puts <<-MSG
+Your repository has no Braid configuration file.  It will be created with the
+current configuration version when you add the first mirror.
+MSG
+          return
+        elsif config.config_version == Config::CURRENT_CONFIG_VERSION
+          puts <<-MSG
+Your configuration file is already at the current configuration version (#{Config::CURRENT_CONFIG_VERSION}).
+MSG
+          return
+        end
+
+        puts <<-MSG
+Your configuration file will be upgraded from configuration version #{config.config_version} to #{Config::CURRENT_CONFIG_VERSION}.
+Other developers on your project will need to use a Braid version compatible
+with configuration version #{Config::CURRENT_CONFIG_VERSION}; see
+https://cristibalan.github.io/braid/config_versions.html .
+
+MSG
+
+        unless config.breaking_change_descs.empty?
+          puts <<-MSG
+The following breaking changes will occur:
+#{config.breaking_change_descs.join('')}
+MSG
+        end
+
+        if options['dry_run']
+          puts <<-MSG
+Run 'braid upgrade-config#{config.breaking_change_descs.empty? ? '' : ' --allow-breaking-changes'}' to perform the upgrade.
+MSG
+        elsif !config.breaking_change_descs.empty? && !options['allow_breaking_changes']
+          raise BraidError, 'You must pass --allow-breaking-changes to accept the breaking changes.'
+        else
+          config.write_db
+          add_config_file
+          had_changes = git.commit('Upgrade configuration')
+          raise InternalError, 'upgrade-config had no changes??' unless had_changes
+          msg 'Configuration upgrade complete.'
+        end
+      end
+    end
+  end
+end

data/lib/braid/config.rb

@@ -2,8 +2,59 @@ require 'yaml'
 require 'json'
 require 'yaml/store'
 
+# Some info about the configuration versioning design:
+# https://github.com/cristibalan/braid/issues/66#issuecomment-354211311
+#
+# Current configuration format:
+# ```
+# {
+#   "config_version": 1,
+#   "mirrors": {
+#     <mirror path: string>: {
+#       "url": <upstream URL: string>,
+#       "path": <remote path: string>,
+#       "branch": <upstream branch: string>,
+#       "tag": <upstream tag: string>,
+#       "revision": <current upstream revision: string>
+#     }
+#   }
+# }
+# ```
+#
+# History of configuration formats understood by current Braid:
+#
+# - Braid 1.1.0, config_version 1:
+#   - "config_version" introduced; mirrors moved to "mirrors"
+#   - Single-file mirrors (f340b0c)
+# - Braid 1.0.18:
+#   - Locked mirrors indicated by absence of "branch" and "tag" attributes, not
+#     presence of "lock" attribute (e6535aa)
+# - Braid 1.0.17:
+#   - Support for full-history mirrors ("squashed": false) removed; "squashed"
+#     attribute no longer written (eb72030)
+# - Braid 1.0.11:
+#   - "remote" attribute no longer written (f8fd088)
+# - Braid 1.0.9:
+#   - .braids -> .braids.json (6806c61)
+# - Braid 1.0.0:
+#   - YAML -> JSON (9d3fa11)
+#   - Support for Subversion mirrors removed ("type": "svn") removed (9d8d390)
+#
+#
+# (Entries that predate the creation of this list have commit IDs for reference.
+# Of course, when adding a new entry, you can't add the commit ID in the same
+# commit, but you don't need to because people can just run `git log` on this
+# file.)
+
 module Braid
   class Config
+
+    MODE_UPGRADE = 1
+    MODE_READ_ONLY = 2
+    MODE_MAY_WRITE = 3
+
+    CURRENT_CONFIG_VERSION = 1
+
     class PathAlreadyInUse < BraidError
       def message
         "path already in use: #{super}"
@@ -15,25 +66,88 @@ module Braid
       end
     end
 
-    def initialize(config_file = CONFIG_FILE, old_config_files = [OLD_CONFIG_FILE])
-      @config_file = config_file
-      (old_config_files + [config_file]).each do |file|
-        next unless File.exist?(file)
+    class RemoveMirrorDueToBreakingChange < StandardError
+    end
+
+    # For upgrade-config command only.  XXX: Ideally would be immutable.
+    attr_reader :config_version, :config_existed, :breaking_change_descs
+
+    # options: config_file, old_config_files, mode
+    def initialize(options = {})
+      @config_file     = options['config_file']      || CONFIG_FILE
+      old_config_files = options['old_config_files'] || [OLD_CONFIG_FILE]
+      @mode            = options['mode']             || MODE_MAY_WRITE
+
+      data = load_config(@config_file, old_config_files)
+      @config_existed = !data.nil?
+      if !@config_existed
+        @config_version = CURRENT_CONFIG_VERSION
+        @db = {}
+      elsif data['config_version'].is_a?(Numeric)
+        @config_version = data['config_version']
+        @db = data['mirrors']
+      else
+        # Before config versioning (Braid < 1.1.0)
+        @config_version = 0
+        @db = data
+      end
+
+      if @config_version > CURRENT_CONFIG_VERSION
+        raise BraidError, <<-MSG
+This version of Braid (#{VERSION}) is too old to understand your project's Braid
+configuration file (version #{@config_version}).  See the instructions at
+https://cristibalan.github.io/braid/config_versions.html to install and use a
+compatible newer version of Braid.
+MSG
+      end
+
+      # In all modes, instantiate all mirrors to scan for breaking changes.
+      @breaking_change_descs = []
+      paths_to_delete = []
+      @db.each do |path, attributes|
         begin
-          store = YAML::Store.new(file)
-          @db = {}
-          store.transaction(true) do
-            store.roots.each do |path|
-              @db[path] = store[path]
-            end
-          end
-          return
-        rescue
-          @db = JSON.parse(file)
-          return if @db
+          mirror = Mirror.new(path, attributes,
+            lambda {|desc| @breaking_change_descs.push(desc)})
+          # In MODE_UPGRADE, update @db now.  In other modes, we won't write the
+          # config if an upgrade is needed, so it doesn't matter that we don't
+          # update @db.
+          #
+          # It's OK to change the values of existing keys during iteration:
+          # https://groups.google.com/d/msg/comp.lang.ruby/r5OI6UaxAAg/SVpU0cktmZEJ
+          write_mirror(mirror) if @mode == MODE_UPGRADE
+        rescue RemoveMirrorDueToBreakingChange
+          # I don't know if deleting during iteration is well-defined in all
+          # Ruby versions we support, so defer the deletion.
+          # ~ matt@mattmccutchen.net, 2017-12-31
+          paths_to_delete.push(path) if @mode == MODE_UPGRADE
         end
       end
-      @db = {}
+      paths_to_delete.each do |path|
+        @db.delete(path)
+      end
+
+      if @mode != MODE_UPGRADE && !@breaking_change_descs.empty?
+        raise BraidError, <<-MSG
+This version of Braid (#{VERSION}) no longer supports a feature used by your
+Braid configuration file (version #{@config_version}).  Run 'braid upgrade-config --dry-run'
+for information about upgrading your configuration file, or see the instructions
+at https://cristibalan.github.io/braid/config_versions.html to install and run a
+compatible older version of Braid.
+MSG
+      end
+
+      if @mode == MODE_MAY_WRITE && @config_version < CURRENT_CONFIG_VERSION
+        raise BraidError, <<-MSG
+This command may need to write to your Braid configuration file,
+but this version of Braid (#{VERSION}) cannot write to your configuration file
+(currently version #{config_version}) without upgrading it to configuration version #{CURRENT_CONFIG_VERSION},
+which would force other developers on your project to upgrade Braid.  Run
+'braid upgrade-config' to proceed with the upgrade, or see the instructions at
+https://cristibalan.github.io/braid/config_versions.html to install and run a
+compatible older version of Braid.
+MSG
+      end
+
     end
 
     def add_from_options(url, options)
@@ -62,6 +176,7 @@ module Braid
     def add(mirror)
       raise PathAlreadyInUse, mirror.path if get(mirror.path)
       write_mirror(mirror)
+      write_db
     end
 
     def remove(mirror)
@@ -71,31 +186,55 @@ module Braid
 
     def update(mirror)
       raise MirrorDoesNotExist, mirror.path unless get(mirror.path)
-      @db.delete(mirror.path)
       write_mirror(mirror)
-    end
-
-    private
-
-    def write_mirror(mirror)
-      @db[mirror.path] = clean_attributes(mirror.attributes)
       write_db
     end
 
+    # Public for upgrade-config command only.
     def write_db
       new_db = {}
       @db.keys.sort.each do |key|
-        new_db[key] = @db[key]
-        new_db[key].keys.each do |k|
-          new_db[key].delete(k) unless Braid::Mirror::ATTRIBUTES.include?(k)
+        new_db[key] = {}
+        Braid::Mirror::ATTRIBUTES.each do |k|
+          new_db[key][k] = @db[key][k] if @db[key].has_key?(k)
         end
       end
+      new_data = {
+        'config_version' => CURRENT_CONFIG_VERSION,
+        'mirrors' => new_db
+      }
       File.open(@config_file, 'wb') do |f|
-        f.write JSON.pretty_generate(new_db)
+        f.write JSON.pretty_generate(new_data)
         f.write "\n"
       end
     end
 
+    private
+
+    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)
+          data = {}
+          store.transaction(true) do
+            store.roots.each do |path|
+              data[path] = store[path]
+            end
+          end
+          return data
+        rescue
+          data = JSON.parse(file)
+          return data if data
+        end
+      end
+      return nil
+    end
+
+    def write_mirror(mirror)
+      @db[mirror.path] = clean_attributes(mirror.attributes)
+    end
+
     def clean_attributes(hash)
       hash.reject { |k, v| v.nil? }
     end

data/lib/braid/mirror.rb

@@ -1,6 +1,9 @@
 module Braid
   class Mirror
-    ATTRIBUTES = %w(url branch revision tag path)
+    # Since Braid 1.1.0, the attributes are written to .braids.json in this
+    # canonical order.  For now, the order is chosen to match what Braid 1.0.22
+    # produced for newly added mirrors.
+    ATTRIBUTES = %w(url branch path tag revision)
 
     class UnknownType < BraidError
       def message
@@ -22,9 +25,44 @@ module Braid
 
     attr_reader :path, :attributes
 
-    def initialize(path, attributes = {})
+    def initialize(path, attributes = {}, breaking_change_cb = DUMMY_BREAKING_CHANGE_CB)
       @path       = path.sub(/\/$/, '')
-      @attributes = attributes
+      @attributes = attributes.dup
+
+      # Not that it's terribly important to check for such an old feature.  This
+      # is mainly to demonstrate the RemoveMirrorDueToBreakingChange mechanism
+      # in case we want to use it for something else in the future.
+      if !@attributes['type'].nil? && @attributes['type'] != 'git'
+        breaking_change_cb.call <<-DESC
+- Mirror '#{path}' is of a Subversion repository, which is no
+  longer supported.  The mirror will be removed from your configuration, leaving
+  the data in the tree.
+DESC
+        raise Config::RemoveMirrorDueToBreakingChange
+      end
+      @attributes.delete('type')
+
+      # Migrate revision locks from Braid < 1.0.18.  We no longer store the
+      # original branch or tag (the user has to specify it again when
+      # unlocking); we simply represent a locked revision by the absence of a
+      # branch or tag.
+      if @attributes['lock']
+        @attributes.delete('lock')
+        @attributes['branch'] = nil
+        @attributes['tag'] = nil
+      end
+
+      # Removal of support for full-history mirrors from Braid < 1.0.17 is a
+      # breaking change for users who wanted to use the imported history in some
+      # way.
+      if !@attributes['squashed'].nil? && @attributes['squashed'] != true
+        breaking_change_cb.call <<-DESC
+- Mirror '#{path}' is full-history, which is no longer supported.
+  It will be changed to squashed.  Upstream history already imported will remain
+  in your project's history and will have no effect on Braid.
+DESC
+      end
+      @attributes.delete('squashed')
     end
 
     def self.new_from_options(url, options = {})
@@ -35,7 +73,7 @@ module Braid
       tag = options['tag']
       branch = options['branch'] || (tag.nil? ? 'master' : nil)
 
-      path = (options['path'] || extract_path_from_url(url)).sub(/\/$/, '')
+      path = (options['path'] || extract_path_from_url(url, options['remote_path'])).sub(/\/$/, '')
       raise PathRequired unless path
 
       remote_path = options['remote_path']
@@ -59,15 +97,68 @@ module Braid
       !!base_revision && git.merge_base(commit, base_revision) == commit
     end
 
-    def versioned_path(revision)
-      "#{revision}:#{self.remote_path}"
+    def upstream_item_for_revision(revision)
+      git.get_tree_item(revision, self.remote_path)
     end
 
+    # Return the arguments that should be passed to "git diff" to diff this
+    # mirror (including uncommitted changes by default), incorporating the given
+    # user-specified arguments.  Having the caller run "git diff" is convenient
+    # for now but violates encapsulation a little; we may have to reorganize the
+    # code in order to add features.
+    def diff_args(user_args = [])
+      upstream_item = upstream_item_for_revision(base_revision)
+
+      # We do not need to spend the time to copy the content outside the
+      # mirror from HEAD because --relative will exclude it anyway.  Rename
+      # detection seems to apply only to the files included in the diff, so we
+      # shouldn't have another bug like
+      # https://github.com/cristibalan/braid/issues/41.
+      base_tree = git.make_tree_with_item(nil, path, upstream_item)
+
+      # Note: --relative does a naive prefix comparison.  If we set (for
+      # example) `--relative=a/b`, that will match an unrelated file or
+      # directory name `a/bb`.  If the mirror is a directory, we can avoid this
+      # by adding a trailing slash to the prefix.
+      #
+      # If the mirror is a file, the only way we can avoid matching a path like
+      # `a/bb` is to pass a path argument to limit the diff.  This means if the
+      # user passes additional path arguments, we won't get the behavior we
+      # expect, which is the intersection of the user-specified paths with the
+      # mirror.  However, it's probably unreasonable for a user to pass path
+      # arguments when diffing a single-file mirror, so we ignore the issue.
+      #
+      # Note: This code doesn't handle various cases in which a directory at the
+      # root of a mirror turns into a file or vice versa.  If that happens,
+      # hopefully the user takes corrective action manually.
+      if upstream_item.is_a?(git.BlobWithMode)
+        # For a single-file mirror, we use the upstream basename for the
+        # upstream side of the diff and the downstream basename for the
+        # downstream side, like what `git diff` does when given two blobs as
+        # arguments.  Use --relative to strip away the entire downstream path
+        # before we add the basenames.
+        return [
+          '--relative=' + path,
+          '--src-prefix=a/' + File.basename(remote_path),
+          '--dst-prefix=b/' + File.basename(path),
+          base_tree,
+          # user_args may contain options, which must come before paths.
+          *user_args,
+          path
+        ]
+      else
+        return [
+          '--relative=' + path + '/',
+          base_tree,
+          *user_args
+        ]
+      end
+    end
+
+    # Precondition: the remote for this mirror is set up.
     def diff
       fetch_base_revision_if_missing
-      remote_hash = git.rev_parse(versioned_path(base_revision))
-      local_hash  = git.tree_hash(path)
-      remote_hash != local_hash ? git.diff_tree(remote_hash, local_hash) : ''
+      git.diff(diff_args)
     end
 
     # Re-fetching the remote after deleting and re-adding it may be slow even if
@@ -79,7 +170,7 @@ module Braid
       begin
         # Without ^{commit}, this will happily pass back an object hash even if
         # the object isn't present.  See the git-rev-parse(1) man page.
-        git.rev_parse(base_revision + "^{commit}")
+        git.rev_parse(base_revision + '^{commit}')
       rescue Operations::UnknownRevision
         fetch
       end
@@ -130,6 +221,11 @@ module Braid
 
     private
 
+    DUMMY_BREAKING_CHANGE_CB = lambda { |desc|
+      raise InternalError, 'Instantiated a mirror using an unsupported ' +
+        'feature outside of configuration loading.'
+    }
+
     def method_missing(name, *args)
       if ATTRIBUTES.find { |attribute| name.to_s =~ /^(#{attribute})(=)?$/ }
         if $2
@@ -159,7 +255,11 @@ module Braid
       hash
     end
 
-    def self.extract_path_from_url(url)
+    def self.extract_path_from_url(url, remote_path)
+      if remote_path
+        return File.basename(remote_path)
+      end
+
       return nil unless url
       name = File.basename(url)