git-multirepo 1.0.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d610a188dbbbaca809a697879cf909120e321965
+  data.tar.gz: 36431ca075fedca8e43cb00eb2c895c253920a9e
+SHA512:
+  metadata.gz: 2e2f18b479298e1eeb135882b07fd6dad6dcc5338746f3096c0821a58d07a150c91121eb1285ad4b8eb5bf88bd4a56ba487fcbd8d99dca6ccabbda280da02e3d
+  data.tar.gz: 13f716a3bd918525167642d6dd87d6bfe413669fb66f3a0b208ac01f6fc93171478fa696af23a8601732b54e53f583126c55dd6858c11f71029f995f809a41ea

data/.gitignore

@@ -0,0 +1,38 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Project-specific
+/.multirepo
+/.multirepo.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in git-multirepo.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    git-multirepo (0.0.1)
+      claide (~> 0.8, >= 0.8.0)
+      colored (~> 1.2)
+      os (~> 0.9.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    claide (0.8.0)
+    colored (1.2)
+    diff-lcs (1.2.5)
+    os (0.9.6)
+    rake (10.4.2)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  git-multirepo!
+  rake (~> 10.0)
+  rspec (~> 3.1.0)

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Michaël Fortin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,132 @@
+# git-multirepo
+
+Track multiple Git repositories side-by-side.
+
+An alternative approach to manage constantly evolving dependencies.
+
+Check out [the project's to-do list](https://www.pivotaltracker.com/n/projects/1256156) to get an idea of upcoming enhancements.
+
+## Motivation
+
+By now the
+[pitfalls](http://somethingsinistral.net/blog/git-submodules-are-probably-not-the-answer/)
+of git submodules are
+[pretty](https://codingkilledthecat.wordpress.com/2012/04/28/why-your-company-shouldnt-use-git-submodules/)
+[well](http://slopjong.de/2013/06/04/git-why-submodules-are-evil/)
+[known](http://stackoverflow.com/questions/12075809/git-submodules-workflow-issues).
+They work when your dependencies are linearly-evolving third-party libraries that you seldom update but they fall apart when it comes to managing your own, constantly evolving dependencies.
+
+Git subtrees are the recommended alternative but have pitfalls of their own:
+
+- They require verbose and error-prone command-line operations. This can become quite tedious when managing more than one or two dependencies.
+- They change the rules of the game when it comes to merges.
+- Each developer has to configure the appropriate remotes and subtrees on his machine if he or she wants to contribute back.
+- Developers must not forget to push changes to dependencies back to the appropriate remotes.
+- Few git GUIs have any kind of subtree integration, so you're stuck with the command-line.
+
+Etc.
+
+## Overview
+
+Using git-multirepo, you can manage your main project and its dependencies as completely independent repositories while still maintaining the ability to checkout a previous revision in a single step and have the project build properly.
+
+A git-multirepo setup looks like this:
+
+```
+MyAwesomeProject
+  |-- AwesomeApp
+  |-- Dependency1
+  |-- Dependency2
+```
+
+In essence:
+
+1. You tell git-multirepo what your dependencies are.
+2. Each time you commit the main repo, git-multirepo tracks what revision of each dependency is required by the project (don't worry, it ensures that you don't forget to commit changes to dependencies beforehand; more on that later).
+3. If you ever want to go back to a previous version of your project, git-multirepo handles checking out the main repo and appropriate revisions of all of its dependencies in a single, seamless operation.
+4. Setting up the project on a new machine is only a single `git clone` and `multi install` away.
+
+## Example
+
+Say you want to track an existing project with git-multirepo:
+
+1. Organize repos on disk in the following manner:
+
+	```
+	MyAwesomeProject
+	  |-- AwesomeApp
+	  |-- Dependency1
+	  |-- Dependency2
+	```
+
+2. `cd` into the *AwesomeApp* directory (aka the "main repo").
+3. Run `multi init`.
+4. You will get prompted to add *Dependency1* and *Dependency2* to multirepo; do so.
+5. git-multirepo reads all required information from dependency repos and initializes itself, storing its metadata files in the main repo, under version control.
+
+From now on, each time you commit the main repo git-multirepo tracks — using a pre-commit hook — which revision of each dependency is required for that main repo revision, and where to get them. The pre-commit hook also ensures that you won't commit the main repo before its dependencies so that you always get a valid state stored under version control.
+
+If you want to add another dependency later on, you can run `multi add ../NewDependency` and you can do the opposite with `multi remove ../SomeOtherDependency`.
+
+If you want to checkout a previous revision (say `e690d`), you use the checkout command: `multi checkout e690d`. This will checkout the main repo's `e690d` revision and all of its dependencies with the proper revisions in detached HEAD state.
+
+If you want to setup your project on another machine, simply clone the main repo in a container directory (see above) and run `multi install`. This will clone each dependency and checkout the appropriate branches.
+
+If you want to stop using git-multirepo, run `multi uninit`. This will remove all traces of git-multirepo from your repository and working copy.
+
+## Advantages
+
+- Makes setting up the project on a new machine a breeze.
+- Works really well for multiple projects that share a common set of constantly evolving dependencies.
+- Each dependency's repository is totally independent from the main repository, which simplifies a lot of things (merges, contributing upstream, etc.) and works well with git GUIs.
+- While the repositories are independent, git-multirepo makes sure to track everything that's required to bring back a previous version of your project in a valid state.
+- Much more approachable to novice developers than submodules or subtrees.
+- Once setup, there is little need for git-multirepo commands, so you are free to use whatever tools you like to work with your git repos.
+- Low possibility of human error (such as forgetting to contribute dependency changes back to the appropriate remotes, forgetting to commit dependencies before committing the main project, etc.)
+- You're not stuck with git-multirepo. It stores its metadata as [YAML](http://www.yaml.org) in the main repo. You can clone and checkout appropriate revisions of your dependencies by hand without git-multirepo if you need to. The information is there, in human-readable form.
+
+| How It Handles... | git-multirepo | git submodules | git subtrees |
+|----------------------------------|:----------------:|:--------------:|:------------:|
+| Working Copy | beside main repo | in main repo | in main repo |
+| Constantly Evolving Dependencies | easy | hard | passable |
+| Merging Changes to Dependencies | easy | hard | passable |
+| Contributing Upstream | easy | easy | passable |
+| Continuous Integration | medium | medium | easy |
+| Complex Branch-Based Workflows | hard* | hard | easy |
+
+(*) This should get better in future versions of git-multirepo.
+
+## Limitations
+
+- git-multirepo should be considered beta at the moment. All of the core features work as described, though. Suggestions and contributions are welcome.
+- The project and its dependencies must live beside each other on disk (for now).
+- There are currently no features to facilitate branch-heavy workflows.
+- You must (ideally) install the tool on your CI server: `gem install git-multirepo`
+
+## Summary of Commands
+
+Here is a quick rundown of commands available to you in git-multirepo:
+
+| Command | Description |
+|---------|-------------|
+| init | Initialize the current repository as a multirepo project. |
+| add | Track an additional dependency with multirepo. |
+| checkout | Checks out the specified commit or branch of the main repo and checks out matching versions of all dependencies. |
+| edit | Opens the .multirepo file in the default text editor. |
+| fetch | Performs a git fetch on all dependencies. |
+| install | Clones and checks out dependencies as defined in the .multirepo file, and installs git-multirepo's local pre-commit hook. |
+| open | Opens all dependencies in the current OS's file explorer. |
+| remove | Removes the specified dependency from multirepo. |
+| update | Force-updates the multirepo lock file. |
+| uninit | Removes all traces of multirepo in the current multirepo repository. |
+
+## Metadata
+
+git-multirepo stores all of its metadata in two files:
+
+| File | Format | Contents |
+|------|--------|----------|
+| .multirepo | YAML | A collection of your project's dependencies. For each dependency, stores its **local path** relative to the main repo, the **remote URL** and the **branch** your project depends upon.
+| .multirepo.lock | YAML | For each dependency, stores the **commit hash** and **branch** on which the dependency was when the main repo was committed. The dependency's **name** is also included but only serves as a reference to make inspecting the lock file easier. |
+
+The information contained in .multirepo and .multirepo.lock allow one-step cloning of a project and all its dependencies, and checking out any prior revision of the main project with appropriate revisions of all of its dependencies, respectively.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/multi

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require "claide"
+require "commands"
+
+MultiRepo::Command.run(ARGV)

data/git-multirepo.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'info'
+
+Gem::Specification.new do |spec|
+  spec.name          = MultiRepo::NAME
+  spec.version       = MultiRepo::VERSION
+  spec.authors       = ["Michaël Fortin"]
+  spec.email         = ["fortinmike@irradiated.net"]
+  spec.summary       = %q{Track multiple Git repositories side-by-side}
+  spec.description   = MultiRepo::DESCRIPTION
+  spec.homepage      = "http://www.irradiated.net"
+  spec.license       = "MIT"
+  
+  spec.required_ruby_version = '~> 2.0'
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.1.0"
+
+  spec.add_runtime_dependency "claide", "~> 0.8", ">= 0.8.0"
+  spec.add_runtime_dependency "colored", "~> 1.2"
+  spec.add_runtime_dependency "os", "~> 0.9.6"
+end

data/lib/commands.rb

@@ -0,0 +1,11 @@
+require_relative "multirepo/commands/command"
+require_relative "multirepo/commands/add"
+require_relative "multirepo/commands/checkout"
+require_relative "multirepo/commands/edit"
+require_relative "multirepo/commands/fetch"
+require_relative "multirepo/commands/init"
+require_relative "multirepo/commands/install"
+require_relative "multirepo/commands/open"
+require_relative "multirepo/commands/remove"
+require_relative "multirepo/commands/uninit"
+require_relative "multirepo/commands/update"

data/lib/git-multirepo.rb

@@ -0,0 +1 @@
+require "multirepo/hooks/pre-commit-hook.rb"

data/lib/info.rb

@@ -0,0 +1,5 @@
+module MultiRepo
+  NAME = "git-multirepo"
+  VERSION = "1.0.0.beta1"
+  DESCRIPTION = "Track multiple Git repositories side-by-side."
+end

data/lib/multirepo/commands/add.rb

@@ -0,0 +1,41 @@
+require "multirepo/utility/console"
+require "multirepo/files/config-file"
+
+module MultiRepo
+  class Add < Command
+    self.command = "add"
+    self.summary = "Track an additional dependency with multirepo."
+    
+    def initialize(argv)
+      @path = argv.shift_argument
+      super
+    end
+    
+    def validate!
+      super
+      help! "You must specify a repository to add as a dependency" unless @path
+    end
+    
+    def run
+      super
+      ensure_multirepo_initialized
+      ensure_repo_exists
+      
+      entry = ConfigEntry.new(Repo.new(@path))
+      if ConfigFile.entry_exists?(entry)
+        Console.log_info("There is already an entry for '#{@path}' in the .multirepo file")
+      else
+        ConfigFile.add_entry(entry)
+        ConfigFile.stage
+        Console.log_step("Added '#{@path}' to the .multirepo file")
+      end
+    rescue MultiRepoException => e
+      Console.log_error(e.message)
+    end
+    
+    def ensure_repo_exists
+      raise MultiRepoException, "There is no folder at path '#{@path}'" unless Dir.exists?(@path)
+      raise MultiRepoException, "'#{@path}' is not a repository" unless Repo.new(@path).exists?
+    end
+  end
+end

data/lib/multirepo/commands/checkout.rb

@@ -0,0 +1,59 @@
+require "multirepo/utility/console"
+
+module MultiRepo
+  class Checkout < Command
+    self.command = "checkout"
+    self.summary = "Checks out the specified commit or branch of the main repo and checks out matching versions of all dependencies."
+    
+    def initialize(argv)
+      @ref = argv.shift_argument
+      @checkout_latest = argv.flag?("latest")
+      super
+    end
+    
+    def run
+      super
+      ensure_multirepo_initialized
+      
+      main_repo = Repo.new(".")
+      initial_revision = main_repo.current_branch || main_repo.head_hash
+                  
+      Console.log_step("Checking out #{@ref} and its dependencies...")
+      
+      unless main_repo.is_clean?
+        raise "Can't checkout #{@ref} because the main repo contains uncommitted changes"
+      end
+      
+      unless main_repo.checkout(@ref)
+        raise MultiRepoException, "Couldn't perform checkout of main repo #{@ref}!"
+      end
+      
+      Console.log_substep("Checked out main repo #{@ref}")
+      
+      unless LockFile.exists?
+        main_repo.checkout(initial_revision)
+        raise MultiRepoException, "The specified revision was not managed by multirepo. Checkout reverted."
+      end
+      
+      if Utils.warn_of_uncommitted_changes(ConfigFile.load)
+        main_repo.checkout(initial_revision)
+        raise "'#{e.path}' contains uncommitted changes. Checkout reverted."
+      end
+      
+      config_entries = ConfigFile.load # Load the post-checkout config entries, which might be different than pre-checkout
+      LockFile.load.each do |lock_entry|
+        config_entry = config_entries.select{ |config_entry| config_entry.id == lock_entry.id }.first
+        revision = @checkout_latest ? lock_entry.branch : lock_entry.head
+        if config_entry.repo.checkout(revision)
+          Console.log_substep("Checked out #{lock_entry.name} #{revision}")
+        else
+          raise MultiRepoException, "Couldn't check out the appropriate version of dependency #{lock_entry.name}"
+        end
+      end
+      
+      Console.log_step("Done!")
+    rescue MultiRepoException => e
+      Console.log_error(e.message)
+    end
+  end
+end

data/lib/multirepo/commands/command.rb

@@ -0,0 +1,41 @@
+require "claide"
+
+require "info"
+require "multirepo/multirepo-exception"
+require "multirepo/config"
+
+module MultiRepo
+  class Command < CLAide::Command
+    self.abstract_command = true
+    self.command = "multi"
+    self.version = VERSION
+    self.description = DESCRIPTION
+    
+    def initialize(argv)
+      Config.instance.verbose = argv.flag?("verbose") ? true : false
+      super
+    end
+    
+    def run
+      validate_in_work_tree
+    end
+    
+    def validate_in_work_tree
+      raise MultiRepoException, "Not a git repository" unless Git.is_inside_git_repo(".")
+    end
+        
+    def install_pre_commit_hook
+      Utils.install_pre_commit_hook
+      Console.log_substep("Installed pre-commit hook")
+    end
+    
+    def update_lock_file
+      LockFile.update
+      Console.log_substep("Updated and staged lock file with current HEAD revisions for all dependencies")
+    end
+
+    def ensure_multirepo_initialized
+      raise MultiRepoException, "multirepo is not initialized in this repository." unless ConfigFile.exists?
+    end
+  end
+end