git-multirepo 1.0.0.beta16 → 1.0.0.beta17
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.gitignore +38 -38
- data/.rspec +2 -2
- data/Gemfile +4 -4
- data/Gemfile.lock +37 -37
- data/LICENSE +22 -22
- data/README.md +139 -137
- data/Rakefile +2 -2
- data/bin/multi +5 -5
- data/git-multirepo.gemspec +29 -29
- data/lib/commands.rb +12 -12
- data/lib/git-multirepo.rb +2 -1
- data/lib/info.rb +4 -4
- data/lib/multirepo/commands/add-command.rb +51 -44
- data/lib/multirepo/commands/branch-command.rb +52 -52
- data/lib/multirepo/commands/checkout-command.rb +84 -84
- data/lib/multirepo/commands/clone-command.rb +53 -53
- data/lib/multirepo/commands/command.rb +32 -36
- data/lib/multirepo/commands/edit-command.rb +21 -21
- data/lib/multirepo/commands/fetch-command.rb +23 -23
- data/lib/multirepo/commands/init-command.rb +53 -53
- data/lib/multirepo/commands/install-command.rb +68 -68
- data/lib/multirepo/commands/open-command.rb +25 -25
- data/lib/multirepo/commands/remove-command.rb +48 -48
- data/lib/multirepo/commands/uninit-command.rb +21 -20
- data/lib/multirepo/commands/update-command.rb +50 -50
- data/lib/multirepo/config.rb +12 -12
- data/lib/multirepo/files/config-entry.rb +37 -37
- data/lib/multirepo/files/config-file.rb +37 -37
- data/lib/multirepo/files/lock-entry.rb +25 -25
- data/lib/multirepo/files/lock-file.rb +39 -38
- data/lib/multirepo/git/branch.rb +27 -27
- data/lib/multirepo/git/change.rb +10 -10
- data/lib/multirepo/git/git.rb +38 -38
- data/lib/multirepo/git/remote.rb +15 -15
- data/lib/multirepo/git/repo.rb +66 -66
- data/lib/multirepo/hooks/post-merge-hook.rb +18 -0
- data/lib/multirepo/hooks/pre-commit-hook.rb +23 -23
- data/lib/multirepo/multirepo-exception.rb +5 -5
- data/lib/multirepo/utility/console.rb +51 -51
- data/lib/multirepo/utility/runner.rb +32 -32
- data/lib/multirepo/utility/utils.rb +41 -41
- data/resources/post-merge +6 -0
- data/resources/pre-commit +5 -5
- data/spec/integration/init_spec.rb +26 -22
- data/spec/spec_helper.rb +89 -89
- metadata +5 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 2d6d791443ed5a120b81f84637cc1122c9f8611e
|
4
|
+
data.tar.gz: d10a799594143bb6fc24681be6fafb07570b9c11
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c5bd81592ddb05d57730b49835106d917e07da5eec4465e5b8a8f58b1213a6f4cf6e613f8b0f2110dc879a19bb4bf81203ba5e4955f65b56924214fab106cee1
|
7
|
+
data.tar.gz: 5d9feaa0464c5dbdb462a100e2bc8e5f89bc2288df2e7e11f81e422c0eb52f152c1174a04394ee6dd4c45793f77fe0a2dce0d4bcbb3cedc97915c92387f91d16
|
data/.gitignore
CHANGED
@@ -1,38 +1,38 @@
|
|
1
|
-
*.gem
|
2
|
-
*.rbc
|
3
|
-
/.config
|
4
|
-
/coverage/
|
5
|
-
/InstalledFiles
|
6
|
-
/pkg/
|
7
|
-
/spec/reports/
|
8
|
-
/test/tmp/
|
9
|
-
/test/version_tmp/
|
10
|
-
/tmp/
|
11
|
-
|
12
|
-
## Specific to RubyMotion:
|
13
|
-
.dat*
|
14
|
-
.repl_history
|
15
|
-
build/
|
16
|
-
|
17
|
-
## Documentation cache and generated files:
|
18
|
-
/.yardoc/
|
19
|
-
/_yardoc/
|
20
|
-
/doc/
|
21
|
-
/rdoc/
|
22
|
-
|
23
|
-
## Environment normalisation:
|
24
|
-
/.bundle/
|
25
|
-
/lib/bundler/man/
|
26
|
-
|
27
|
-
# for a library or gem, you might want to ignore these files since the code is
|
28
|
-
# intended to run in multiple environments; otherwise, check them in:
|
29
|
-
# Gemfile.lock
|
30
|
-
# .ruby-version
|
31
|
-
# .ruby-gemset
|
32
|
-
|
33
|
-
# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
|
34
|
-
.rvmrc
|
35
|
-
|
36
|
-
# Project-specific
|
37
|
-
/.multirepo
|
38
|
-
/.multirepo.lock
|
1
|
+
*.gem
|
2
|
+
*.rbc
|
3
|
+
/.config
|
4
|
+
/coverage/
|
5
|
+
/InstalledFiles
|
6
|
+
/pkg/
|
7
|
+
/spec/reports/
|
8
|
+
/test/tmp/
|
9
|
+
/test/version_tmp/
|
10
|
+
/tmp/
|
11
|
+
|
12
|
+
## Specific to RubyMotion:
|
13
|
+
.dat*
|
14
|
+
.repl_history
|
15
|
+
build/
|
16
|
+
|
17
|
+
## Documentation cache and generated files:
|
18
|
+
/.yardoc/
|
19
|
+
/_yardoc/
|
20
|
+
/doc/
|
21
|
+
/rdoc/
|
22
|
+
|
23
|
+
## Environment normalisation:
|
24
|
+
/.bundle/
|
25
|
+
/lib/bundler/man/
|
26
|
+
|
27
|
+
# for a library or gem, you might want to ignore these files since the code is
|
28
|
+
# intended to run in multiple environments; otherwise, check them in:
|
29
|
+
# Gemfile.lock
|
30
|
+
# .ruby-version
|
31
|
+
# .ruby-gemset
|
32
|
+
|
33
|
+
# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
|
34
|
+
.rvmrc
|
35
|
+
|
36
|
+
# Project-specific
|
37
|
+
/.multirepo
|
38
|
+
/.multirepo.lock
|
data/.rspec
CHANGED
@@ -1,2 +1,2 @@
|
|
1
|
-
--color
|
2
|
-
--require spec_helper
|
1
|
+
--color
|
2
|
+
--require spec_helper
|
data/Gemfile
CHANGED
@@ -1,4 +1,4 @@
|
|
1
|
-
source 'https://rubygems.org'
|
2
|
-
|
3
|
-
# Specify your gem's dependencies in git-multirepo.gemspec
|
4
|
-
gemspec
|
1
|
+
source 'https://rubygems.org'
|
2
|
+
|
3
|
+
# Specify your gem's dependencies in git-multirepo.gemspec
|
4
|
+
gemspec
|
data/Gemfile.lock
CHANGED
@@ -1,37 +1,37 @@
|
|
1
|
-
PATH
|
2
|
-
remote: .
|
3
|
-
specs:
|
4
|
-
git-multirepo (0.0.1)
|
5
|
-
claide (~> 0.8, >= 0.8.0)
|
6
|
-
colored (~> 1.2)
|
7
|
-
os (~> 0.9.6)
|
8
|
-
|
9
|
-
GEM
|
10
|
-
remote: https://rubygems.org/
|
11
|
-
specs:
|
12
|
-
claide (0.8.0)
|
13
|
-
colored (1.2)
|
14
|
-
diff-lcs (1.2.5)
|
15
|
-
os (0.9.6)
|
16
|
-
rake (10.4.2)
|
17
|
-
rspec (3.1.0)
|
18
|
-
rspec-core (~> 3.1.0)
|
19
|
-
rspec-expectations (~> 3.1.0)
|
20
|
-
rspec-mocks (~> 3.1.0)
|
21
|
-
rspec-core (3.1.7)
|
22
|
-
rspec-support (~> 3.1.0)
|
23
|
-
rspec-expectations (3.1.2)
|
24
|
-
diff-lcs (>= 1.2.0, < 2.0)
|
25
|
-
rspec-support (~> 3.1.0)
|
26
|
-
rspec-mocks (3.1.3)
|
27
|
-
rspec-support (~> 3.1.0)
|
28
|
-
rspec-support (3.1.2)
|
29
|
-
|
30
|
-
PLATFORMS
|
31
|
-
ruby
|
32
|
-
|
33
|
-
DEPENDENCIES
|
34
|
-
bundler (~> 1.7)
|
35
|
-
git-multirepo!
|
36
|
-
rake (~> 10.0)
|
37
|
-
rspec (~> 3.1.0)
|
1
|
+
PATH
|
2
|
+
remote: .
|
3
|
+
specs:
|
4
|
+
git-multirepo (0.0.1)
|
5
|
+
claide (~> 0.8, >= 0.8.0)
|
6
|
+
colored (~> 1.2)
|
7
|
+
os (~> 0.9.6)
|
8
|
+
|
9
|
+
GEM
|
10
|
+
remote: https://rubygems.org/
|
11
|
+
specs:
|
12
|
+
claide (0.8.0)
|
13
|
+
colored (1.2)
|
14
|
+
diff-lcs (1.2.5)
|
15
|
+
os (0.9.6)
|
16
|
+
rake (10.4.2)
|
17
|
+
rspec (3.1.0)
|
18
|
+
rspec-core (~> 3.1.0)
|
19
|
+
rspec-expectations (~> 3.1.0)
|
20
|
+
rspec-mocks (~> 3.1.0)
|
21
|
+
rspec-core (3.1.7)
|
22
|
+
rspec-support (~> 3.1.0)
|
23
|
+
rspec-expectations (3.1.2)
|
24
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
25
|
+
rspec-support (~> 3.1.0)
|
26
|
+
rspec-mocks (3.1.3)
|
27
|
+
rspec-support (~> 3.1.0)
|
28
|
+
rspec-support (3.1.2)
|
29
|
+
|
30
|
+
PLATFORMS
|
31
|
+
ruby
|
32
|
+
|
33
|
+
DEPENDENCIES
|
34
|
+
bundler (~> 1.7)
|
35
|
+
git-multirepo!
|
36
|
+
rake (~> 10.0)
|
37
|
+
rspec (~> 3.1.0)
|
data/LICENSE
CHANGED
@@ -1,22 +1,22 @@
|
|
1
|
-
The MIT License (MIT)
|
2
|
-
|
3
|
-
Copyright (c) 2015 Michaël Fortin
|
4
|
-
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
7
|
-
in the Software without restriction, including without limitation the rights
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
10
|
-
furnished to do so, subject to the following conditions:
|
11
|
-
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
13
|
-
copies or substantial portions of the Software.
|
14
|
-
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
-
SOFTWARE.
|
22
|
-
|
1
|
+
The MIT License (MIT)
|
2
|
+
|
3
|
+
Copyright (c) 2015 Michaël Fortin
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
+
SOFTWARE.
|
22
|
+
|
data/README.md
CHANGED
@@ -1,138 +1,140 @@
|
|
1
|
-
![git-multirepo](images/logo.png)
|
2
|
-
|
3
|
-
# git-multirepo
|
4
|
-
|
5
|
-
[![Gem Version](https://badge.fury.io/rb/git-multirepo.svg)](http://badge.fury.io/rb/git-multirepo)
|
6
|
-
|
7
|
-
Track multiple Git repositories side-by-side.
|
8
|
-
|
9
|
-
An alternative approach to manage constantly evolving dependencies.
|
10
|
-
|
11
|
-
Check out [the project's to-do list](https://www.pivotaltracker.com/n/projects/1256156) to get an idea of upcoming enhancements.
|
12
|
-
|
13
|
-
## Motivation
|
14
|
-
|
15
|
-
By now the
|
16
|
-
[pitfalls](http://somethingsinistral.net/blog/git-submodules-are-probably-not-the-answer/)
|
17
|
-
of git submodules are
|
18
|
-
[pretty](https://codingkilledthecat.wordpress.com/2012/04/28/why-your-company-shouldnt-use-git-submodules/)
|
19
|
-
[well](http://slopjong.de/2013/06/04/git-why-submodules-are-evil/)
|
20
|
-
[known](http://stackoverflow.com/questions/12075809/git-submodules-workflow-issues).
|
21
|
-
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.
|
22
|
-
|
23
|
-
Git subtrees are the recommended alternative but have pitfalls of their own:
|
24
|
-
|
25
|
-
- They require verbose and error-prone command-line operations. This can become quite tedious when managing more than one or two dependencies.
|
26
|
-
- They change the rules of the game when it comes to merges.
|
27
|
-
- Each developer has to configure the appropriate remotes and subtrees on his machine if he or she wants to contribute back.
|
28
|
-
- Developers must not forget to push changes to dependencies back to the appropriate remotes.
|
29
|
-
- Few git GUIs have any kind of subtree integration, so you're stuck with the command-line.
|
30
|
-
|
31
|
-
Etc.
|
32
|
-
|
33
|
-
## Overview
|
34
|
-
|
35
|
-
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.
|
36
|
-
|
37
|
-
A git-multirepo setup looks like this:
|
38
|
-
|
39
|
-
```
|
40
|
-
MyAwesomeProject
|
41
|
-
|-- AwesomeApp
|
42
|
-
|-- Dependency1
|
43
|
-
|-- Dependency2
|
44
|
-
```
|
45
|
-
|
46
|
-
In essence:
|
47
|
-
|
48
|
-
1. You tell git-multirepo what your dependencies are.
|
49
|
-
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).
|
50
|
-
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.
|
51
|
-
4. Setting up the project on a new machine is only a single `git clone` and `multi install` away.
|
52
|
-
|
53
|
-
## Example
|
54
|
-
|
55
|
-
Say you want to track an existing project with git-multirepo:
|
56
|
-
|
57
|
-
1. Organize repos on disk in the following manner:
|
58
|
-
|
59
|
-
```
|
60
|
-
MyAwesomeProject
|
61
|
-
|-- AwesomeApp
|
62
|
-
|-- Dependency1
|
63
|
-
|-- Dependency2
|
64
|
-
```
|
65
|
-
|
66
|
-
2. `cd` into the *AwesomeApp* directory (aka the "main repo").
|
67
|
-
3. Run `multi init`.
|
68
|
-
4. You will get prompted to add *Dependency1* and *Dependency2* to multirepo; do so.
|
69
|
-
5. git-multirepo reads all required information from dependency repos and initializes itself, storing its metadata files in the main repo, under version control.
|
70
|
-
|
71
|
-
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.
|
72
|
-
|
73
|
-
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`.
|
74
|
-
|
75
|
-
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.
|
76
|
-
|
77
|
-
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.
|
78
|
-
|
79
|
-
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.
|
80
|
-
|
81
|
-
## Advantages
|
82
|
-
|
83
|
-
- Makes setting up the project on a new machine a breeze.
|
84
|
-
- Works really well for multiple projects that share a common set of constantly evolving dependencies.
|
85
|
-
- 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.
|
86
|
-
- 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.
|
87
|
-
- Much more approachable to novice developers than submodules or subtrees.
|
88
|
-
- 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.
|
89
|
-
- 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.)
|
90
|
-
- 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.
|
91
|
-
|
92
|
-
| How It Handles... | git-multirepo | git submodules | git subtrees |
|
93
|
-
|----------------------------------|:----------------:|:--------------:|:------------:|
|
94
|
-
| Working Copy | beside main repo | in main repo | in main repo |
|
95
|
-
| Constantly Evolving Dependencies | easy | hard | passable |
|
96
|
-
| Merging Changes to Dependencies | easy | hard | passable |
|
97
|
-
| Contributing Upstream | easy | easy | passable |
|
98
|
-
| Continuous Integration | medium | medium | easy |
|
99
|
-
| Complex Branch-Based Workflows | hard* | hard | easy |
|
100
|
-
|
101
|
-
(*) This should get better in future versions of git-multirepo.
|
102
|
-
|
103
|
-
## Limitations
|
104
|
-
|
105
|
-
- git-multirepo should be considered beta at the moment. All of the core features work as described, though. Suggestions and contributions are welcome.
|
106
|
-
- The project and its dependencies must live beside each other on disk (for now).
|
107
|
-
- There are currently no features to facilitate branch-heavy workflows.
|
108
|
-
- You must (ideally) install the tool on your CI server: `gem install git-multirepo`
|
109
|
-
|
110
|
-
## Summary of Commands
|
111
|
-
|
112
|
-
Here is a quick rundown of commands available to you in git-multirepo:
|
113
|
-
|
114
|
-
| Command | Description |
|
115
|
-
|---------|-------------|
|
116
|
-
| init | Initialize the current repository as a multirepo project. |
|
117
|
-
| add | Track an additional dependency with multirepo. |
|
118
|
-
| branch | Create and/or checkout a new branch for all repos. |
|
119
|
-
| checkout | Checks out the specified commit or branch of the main repo and checks out matching versions of all dependencies. |
|
120
|
-
| clone | Clones the specified repository in a subfolder, then
|
121
|
-
| edit | Opens the .multirepo file in the default text editor. |
|
122
|
-
| fetch | Performs a git fetch on all dependencies. |
|
123
|
-
| install | Clones and checks out dependencies as defined in the .multirepo file, and installs git-multirepo's local pre-commit hook. |
|
124
|
-
| open | Opens all dependencies in the current OS's file explorer. |
|
125
|
-
| remove | Removes the specified dependency from multirepo. |
|
126
|
-
| update | Force-updates the multirepo lock file. |
|
127
|
-
| uninit | Removes all traces of multirepo in the current multirepo repository. |
|
128
|
-
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
|
|
136
|
-
|
137
|
-
|
1
|
+
![git-multirepo](images/logo.png)
|
2
|
+
|
3
|
+
# git-multirepo
|
4
|
+
|
5
|
+
[![Gem Version](https://badge.fury.io/rb/git-multirepo.svg)](http://badge.fury.io/rb/git-multirepo)
|
6
|
+
|
7
|
+
Track multiple Git repositories side-by-side.
|
8
|
+
|
9
|
+
An alternative approach to manage constantly evolving dependencies.
|
10
|
+
|
11
|
+
Check out [the project's to-do list](https://www.pivotaltracker.com/n/projects/1256156) to get an idea of upcoming enhancements.
|
12
|
+
|
13
|
+
## Motivation
|
14
|
+
|
15
|
+
By now the
|
16
|
+
[pitfalls](http://somethingsinistral.net/blog/git-submodules-are-probably-not-the-answer/)
|
17
|
+
of git submodules are
|
18
|
+
[pretty](https://codingkilledthecat.wordpress.com/2012/04/28/why-your-company-shouldnt-use-git-submodules/)
|
19
|
+
[well](http://slopjong.de/2013/06/04/git-why-submodules-are-evil/)
|
20
|
+
[known](http://stackoverflow.com/questions/12075809/git-submodules-workflow-issues).
|
21
|
+
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.
|
22
|
+
|
23
|
+
Git subtrees are the recommended alternative but have pitfalls of their own:
|
24
|
+
|
25
|
+
- They require verbose and error-prone command-line operations. This can become quite tedious when managing more than one or two dependencies.
|
26
|
+
- They change the rules of the game when it comes to merges.
|
27
|
+
- Each developer has to configure the appropriate remotes and subtrees on his machine if he or she wants to contribute back.
|
28
|
+
- Developers must not forget to push changes to dependencies back to the appropriate remotes.
|
29
|
+
- Few git GUIs have any kind of subtree integration, so you're stuck with the command-line.
|
30
|
+
|
31
|
+
Etc.
|
32
|
+
|
33
|
+
## Overview
|
34
|
+
|
35
|
+
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.
|
36
|
+
|
37
|
+
A git-multirepo setup looks like this:
|
38
|
+
|
39
|
+
```
|
40
|
+
MyAwesomeProject
|
41
|
+
|-- AwesomeApp
|
42
|
+
|-- Dependency1
|
43
|
+
|-- Dependency2
|
44
|
+
```
|
45
|
+
|
46
|
+
In essence:
|
47
|
+
|
48
|
+
1. You tell git-multirepo what your dependencies are.
|
49
|
+
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).
|
50
|
+
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.
|
51
|
+
4. Setting up the project on a new machine is only a single `git clone` and `multi install` away.
|
52
|
+
|
53
|
+
## Example
|
54
|
+
|
55
|
+
Say you want to track an existing project with git-multirepo:
|
56
|
+
|
57
|
+
1. Organize repos on disk in the following manner:
|
58
|
+
|
59
|
+
```
|
60
|
+
MyAwesomeProject
|
61
|
+
|-- AwesomeApp
|
62
|
+
|-- Dependency1
|
63
|
+
|-- Dependency2
|
64
|
+
```
|
65
|
+
|
66
|
+
2. `cd` into the *AwesomeApp* directory (aka the "main repo").
|
67
|
+
3. Run `multi init`.
|
68
|
+
4. You will get prompted to add *Dependency1* and *Dependency2* to multirepo; do so.
|
69
|
+
5. git-multirepo reads all required information from dependency repos and initializes itself, storing its metadata files in the main repo, under version control.
|
70
|
+
|
71
|
+
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.
|
72
|
+
|
73
|
+
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`.
|
74
|
+
|
75
|
+
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.
|
76
|
+
|
77
|
+
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.
|
78
|
+
|
79
|
+
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.
|
80
|
+
|
81
|
+
## Advantages
|
82
|
+
|
83
|
+
- Makes setting up the project on a new machine a breeze.
|
84
|
+
- Works really well for multiple projects that share a common set of constantly evolving dependencies.
|
85
|
+
- 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.
|
86
|
+
- 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.
|
87
|
+
- Much more approachable to novice developers than submodules or subtrees.
|
88
|
+
- 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.
|
89
|
+
- 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.)
|
90
|
+
- 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.
|
91
|
+
|
92
|
+
| How It Handles... | git-multirepo | git submodules | git subtrees |
|
93
|
+
|----------------------------------|:----------------:|:--------------:|:------------:|
|
94
|
+
| Working Copy | beside main repo | in main repo | in main repo |
|
95
|
+
| Constantly Evolving Dependencies | easy | hard | passable |
|
96
|
+
| Merging Changes to Dependencies | easy | hard | passable |
|
97
|
+
| Contributing Upstream | easy | easy | passable |
|
98
|
+
| Continuous Integration | medium | medium | easy |
|
99
|
+
| Complex Branch-Based Workflows | hard* | hard | easy |
|
100
|
+
|
101
|
+
(*) This should get better in future versions of git-multirepo.
|
102
|
+
|
103
|
+
## Limitations
|
104
|
+
|
105
|
+
- git-multirepo should be considered beta at the moment. All of the core features work as described, though. Suggestions and contributions are welcome.
|
106
|
+
- The project and its dependencies must live beside each other on disk (for now).
|
107
|
+
- There are currently no features to facilitate branch-heavy workflows.
|
108
|
+
- You must (ideally) install the tool on your CI server: `gem install git-multirepo`
|
109
|
+
|
110
|
+
## Summary of Commands
|
111
|
+
|
112
|
+
Here is a quick rundown of commands available to you in git-multirepo:
|
113
|
+
|
114
|
+
| Command | Description |
|
115
|
+
|---------|-------------|
|
116
|
+
| init | Initialize the current repository as a multirepo project. |
|
117
|
+
| add | Track an additional dependency with multirepo. |
|
118
|
+
| branch | Create and/or checkout a new branch for all repos. |
|
119
|
+
| checkout | Checks out the specified commit or branch of the main repo and checks out matching versions of all dependencies. |
|
120
|
+
| clone | Clones the specified repository in a subfolder, then installs it. |
|
121
|
+
| edit | Opens the .multirepo file in the default text editor. |
|
122
|
+
| fetch | Performs a git fetch on all dependencies. |
|
123
|
+
| install | Clones and checks out dependencies as defined in the .multirepo file, and installs git-multirepo's local pre-commit hook. |
|
124
|
+
| open | Opens all dependencies in the current OS's file explorer. |
|
125
|
+
| remove | Removes the specified dependency from multirepo. |
|
126
|
+
| update | Force-updates the multirepo lock file. |
|
127
|
+
| uninit | Removes all traces of multirepo in the current multirepo repository. |
|
128
|
+
|
129
|
+
To read more about each command, use the `--help` flag (e.g. `$ multi clone --help`).
|
130
|
+
|
131
|
+
## Metadata
|
132
|
+
|
133
|
+
git-multirepo stores all of its metadata in two files:
|
134
|
+
|
135
|
+
| File | Format | Contents |
|
136
|
+
|------|--------|----------|
|
137
|
+
| .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 **work branch** your project depends upon.
|
138
|
+
| .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. |
|
139
|
+
|
138
140
|
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.
|