patmaddox/giternal

non-sucky git externals

giternal is unmaintained¶ ↑

If you want the functionality that giternal provides, but in a tool that’s being maintained, you should consider:

• myrepos.branchable.com

• github.com/RichiH/vcsh

• forking it

Thanks to @jwhitley for the suggested alternatives.

Installation¶ ↑

‘gem install giternal`

Why giternal¶ ↑

There are a couple tools out there that keep track of git externals for you. Git submodules are built in, and braid is a different project. They both have problems that prevent them from using those externals collaboratively.

In a nutshell, git submodules keep a reference to the head of each external project. This means that if Joe and Sarah each make non-conflicting changes to their externals, and push the external reference in the main project, one of them will get a conflict on update. Braid doesn’t treat the externals as being separate from the main project, so any commits you make will go to the parent instead of the external.

In order to demonstrate these issues more concretely, I’ve written a script that will simulate the workflow of making changes to an external, pushing it upstream, and pulling it into another project. You’ll notice in the submodule example that there’s a conflict when updating the main repo, and files are missing in the local external after update. In the braid example, the changes never make it upstream. This script checks to see if a tool allows you to not only track dependencies but collaborate as well. To execute it, run

ruby test_trackers.rb giternal|submodules|braid

Using it¶ ↑

Put a file in your project named .giternal.yml or config/giternal.yml, that looks like this:

local_dir_name:
  repo: git://path/to/repo.git
  path: local/sub/dir

As an example, here’s how you’d track rspec:

rspec:
  repo: git://github.com/dchelimsky/rspec.git
  path: vendor/plugins

To pull the externals into your workspace, run “giternal update”. You should add vendor/plugins/rspec to .gitignore to keep the files from being added to your main repo.

Deploying externals¶ ↑

I frequently use a cap task that changes to deploy_root and runs “giternal update” to pull all the externals. The downside with this approach is that you’ll get the bleeding edge of your external, and you may want to use a particular version that you’ve tested and know works with your app. Enter freezing.

Make sure your working dir is clean and then run “giternal freeze”. The externals are no longer separate repos - the history was zipped up so that the external can be unfrozen later. Each external is added to the git index, so all you have to do is commit. You’ve got a self-contained external that is frozen to a working version, suitable for deploy.

After you’ve tagged your release, you can unfreeze the giternal with “giternal unfreeze” and get back to development.

How I want to work with externals¶ ↑

When tracking externals, the most important thing is knowing my libraries work together, and second I can try to stay up to date. When I update an external, I would run rake. If it passes, keep that version. If not, look at what it would take to take for my code and the library code to work. If I feel like I can do it, I do, otherwise I unfreeze and stay on the older working version.

THANK YOUs¶ ↑

Rollcall of awesome people who have contributed to giternal:

Brian Takita & Honkster Team - ability to specify individual repos for

freeze/unfreeze/update

Copyright¶ ↑

Copyright © 2009-2011 Pat Maddox. See LICENSE for details.

giternal's Issues

Undo unfreeze with freeze leaves modified .git.frozen.tgz

Lets say module M is currently frozen.

I decide to unfreeze module M to continue development -- giternal now deletes the files from the frozen module and adds those deletes to the index.

Now I realize I unfroze by mistake and I want to "undo" the unfreeze. I have two options:

1. git reset --hard HEAD, or

2. giternal freeze.

Both of these sort of result in problems. Doing Option 1 leaves a .git directory in each module which should not exist, and needs to be manually deleted. Doing Option 2 leaves modified .git.frozen.tgz files in the index for each module.

Option 2 is "better" since the "fix" is as simple as git reset --hard HEAD.

I'm not sure what the best solution to this is, but perhaps giternal should have an "undo" command that reverses the last operation if the commit hasn't yet been done? Or alternatively, giternal freeze could check if the module was already frozen in the last commit and automatically revert to the old .git.frozen.tgz files.

gitternal update should add newline to .gitignore

If a newline isn't present in .gitignore, giternal doesn't add one, leading to a line like this:

MY_FILEmy_repos/path

giternal -h should be more helpful

I would love for it to say about as much as the readme.
maybe giternal --help-lots

Install documentation

Hi,
Can you provide some installation instructions please ? (for people not familiar with ruby)

.git.frozen.tgz should NOT be added to repo while freezing

First off, great work with giternal. It was exactly the tool I was looking for to manage vendoring in a simple, yet flexible manner. The one issue I encountered was the inclusion of .git.frozen.tgz in the main repo, when it is frozen. I believe this is the line responsible for that happening.

https://github.com/patmaddox/giternal/blob/master/lib/giternal/repository.rb#L53

IMHO, I don't think this should be included in the main repo, since it is only to keep track of the history of the dependencies. By including this in the main repo, any push commands push the entire repo along with the history of all the dependencies, which is not desirable.

I managed a workaround by manually calling git checkout .git.frozen.tgz for all the vendored libraries, but a more elegant solution would be to build this into the rubygem.

Let me know your thoughts.

Does not work if `pwd` has a space

Let's say your project is in "/home/foouser/Programming Projects/fooproject/". When executing giternal update from that directory, you'd get the error:

"sh: line 0: cd: /home/foouser/Programming: No such file or directory
..updated"

Allow freezing at a revision

Is it possible to freeze an external at a given revision or on another branch?