Usage and examples

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

Notes

• these instructions are for braid version 0.5+
• braid requires git version 1.6+
• you must be in a repository with at least one commit in it

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. Mirrors are squashed by default, which is what you’ll generally want 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.

Built in help

You can invoke the built in help to see all the available commands or the flags or a command:

braid help braid help add # or braid add —help

Adding a mirror

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

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

Updating mirrors with conflicts

If a braid update creates a conflict, braid will stop execution and leave the partially commited files in your working copy, just like a normal git merge conflict would.

You will then have to resolve all conflicts and manually run git commit. The commit message is already prepared.

If you want to cancel the braid update and the merge, you’ll have to reset your working copy and index with git reset --hard.

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

Working in a team

There’s nothing special you need to do.

\# user 1 braid add some/remote/blah.git lib/blah git push \# user 2 git pull braid update lib/blah

Changing a full (non-squashed) mirror (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. It doesn’t hurt to double check though. 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

Now just add the remote again, as usual:

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

And reapply your changes to it and commit them:

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