Usage and examples

Please add usage scenarios or links to articles that mention special braid techniques below.

VERY IMPORTANT

These instructions are for Braid version 0.4.0. An upgrade to this version is highly recommended.

Notes

• only git version 1.5.4.5+ and up have been tested
• most scenarios assume you have a repository created with at least one commit in it to allow branching

Starting point

git init project
cd project
touch README
git add README
git commit -m "initial commit"

There are two types of mirrors in braid: squashed and full. The default is squashed, which you’ll generally want to use because they’re faster and don’t pollute your history with commits from the mirrors.

Full mirrors are useful when you want to view imported history in your own project. You usually want this if the mirror is also a repository you have access to, for example, when using shared code across projects.

Please note that you cannot change between mirror types after the initial add. You’ll have to remove the mirror and add it again.

Adding a mirror

braid add git://github.com/rails/rails.git vendor/rails
braid add -p git://github.com/mbleigh/seed-fu.git

Hint: You need to merge the “braid/track” branch to your current branch to see the effect of the add command at this point. This may not be required in a later version but exists as a safety precaution in the current version.

Adding mirrors with revisions

braid add --revision bf1b1e0 git://github.com/rails/rails.git vendor/rails
braid add --rails_plugin --type svn --revision 32 http://oauth-plugin.googlecode.com/svn/trunk/oauth_plugin

Adding mirrors with full history

braid add --full --type svn --revision 403 http://oauth.googlecode.com/svn/code/ruby/oauth vendor/oauth
braid add --full --rails_plugin git://github.com/mislav/will_paginate.git vendor/plugins/will_paginate

Updating mirrors

braid update vendor/plugins/cache_fu
braid update

Locking and unlocking mirrors

braid update --revision 6c1c16b vendor/rails
braid update --head vendor/rails

Showing local changes made to mirrors

braid diff vendor/rails

Changing a full (non-squashed) mirror (from 0.3.x or created with—full) to a squashed mirror

Unfortunately, there’s no easy or automatic way to do this so you’ll have to get your hands dirty a bit.

Use braid diff to get the changes made to the mirror, and save them to a happy_place.diff.

braid diff vendor/plugins/acts_as_state_machine >> ../happy_place.diff
braid remove vendor/plugins/acts_as_state_machine

If you have local changes, at this point you’ll get conflicts. You don’t actually care about them, because you already have them in your diff file. If doesn’t hurt to double check tho. After you’re positive that you have those changes someplace, just discard them and commit the merge.

git rm vendor/plugins/acts_as_state_machine/lib/acts_as_state_machine.rb
git commit -m "Merge braid/track"

Now just add the remote again, as usual:

braid add -p -t svn http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/trunk
git merge braid/track

And reapply your changes to it and commit them:

patch -p1 < ../happy_place.diff
git commit -m "reapply custom changes to aasm"

Working in a team

You only need this if you want to run braid update from more than one clone of your repository. If you work alone or if only one developer uses braid to track mirrors, you don’t need this. If you’re one developer working from two computers (or two different local clones for that matter), you need this.

WARNING: To prevent any mishaps when working in a team, updates to the tracked mirrors (that is, running braid update) should be made carefully by one developer and then pushed back. The main concern is that if two people update the mirrors they’ll potentially need to fix conflicts in the braid/track branch, which is probably not a fun task.

First, you’ll need to push the braid/track branch upstream. Then, after every braid add/udpate/remove it should be pushed again.

git push origin braid/track:refs/heads/braid/track
\# if you want git push and pull to include the braid/track every time, you need some config changes
git config "branch.braid/track.merge" refs/heads/braid/track
git config "branch.braid/track.remote" origin

Then, people that wish to use braid to update some mirrors need to pull the branch into their local repository and setup their remotes before they update.

git branch -f braid/track origin/braid/track
braid setup
git pull \# includes work branch
\# now they can update
braid update vendor/rails
\# and then push back the braid/track branch
git push origin braid/track
\# or just push everything, which will include the braid/track branch
git push