Why git_remote_branch?

git_remote_branch is a simple command-line tool that makes it very easy to manipulate branches published in shared repositories.

It achieves this goal by sticking to a few principles:

• keep grb's commands extremely regular (they all look alike)

• support aliases for commands

• print all commands it runs on your behalf in red, so you eventually learn them

Another nice thing about git_remote_branch is that it can simply explain a command (print out all the corresponding git commands) instead of running them on your behalf.

Note: git_remote_branch assumes that the local and remote branches have the same name. Multiple remote repositories (or origins) are supported.

Installation

sudo gem install git_remote_branch --include-dependencies

If you have an old version of Rubygems, you may have to manually install the “colored” gem.

sudo gem install colored

If you're on Windows, you must also install “win32console” manually (before or after installing git_remote_branch doesn't matter).

gem install win32console colored

See the “Bleeding edge and development” section the end of this document for more details about fiddling with the source of git_remote_branch or running it with Ruby 1.9 (yes, it works).

Usage

Notes:

• parts between brackets are optional

• When 'origin_server' is not specified, the name 'origin' is assumed.

Available commands (with aliases):

Help

$ grb [-h|help]    #=> Displays help

create (alias: new)

Create a new local branch as well as a corresponding remote branch based on the branch you currently have checked out. Track the new remote branch. Checkout the new branch.

$ grb create branch_name [origin_server]

publish (aliases: remotize, share)

Publish an existing local branch to the remote server. Set up the local branch to track the new remote branch.

$ grb publish branch_name [origin_server]

delete (aliases: destroy, kill, remove, rm)

Delete the remote branch then delete the local branch. The local branch is not deleted if there are pending changes.

$ grb delete branch_name [origin_server]

track (aliases: follow grab fetch)

Track an existing remote branch locally and checkout the branch.

$ grb track branch_name [origin_server]

rename (aliases: rn mv move)

Rename a remote branch and its local tracking branch. The branch you want to rename must be checked out.

# On branch to be renamed
$ grb rename new_branch_name [origin_server]

unfork

Unforks the branch. Useful for the following use case:

• you forked a repository on github, e.g. geekq/gettext is a fork of mutoh/gettext

• you are making changes, commiting, sending pull requests, merging

• you upstream accepts your patches but modifies them before commiting

• you do not want to maintain your version of library, just to use it for experimentation and providing changes upstream

• so you want to closely follow the upstream and want your 'master' to exactly follow the upstream master

Usage:

# On branch to be unforked
$ grb unfork remote_branch_ref [origin_server]

Example:

$ git remote
upstream
origin
$ git checkout master
$ grb unfork upstream/master origin
# resets the local master branch and origin/master to the upstream/master
# now you can make branches out of your master again and work on new patches

explain

All commands can be prepended by the word 'explain'. Instead of executing the command, git_remote_branch will simply output the list of commands you need to run to accomplish that goal. Examples:

$ grb explain create
git_remote_branch version 0.3.0
List of operations to do to create a new remote branch and track it locally:
git push origin master:refs/heads/branch_to_create
git fetch origin
git branch --track branch_to_create origin/branch_to_create
git checkout branch_to_create

Explain your specific case:

$ grb explain create my_branch github
git_remote_branch version 0.3.0
List of operations to do to create a new remote branch and track it locally:
git push github master:refs/heads/my_branch
git fetch github
git branch --track my_branch github/my_branch
git checkout my_branch

This, of course, works for each of the grb commands.

More on git_remote_branch

• Documentation: grb.rubyforge.org

• News: programblings.com/category/git/git_remote_branch/

• Bug tracker: git-remote-branch.lighthouseapp.com/projects/19198-git_remote_branch/overview

• Code: github.com/webmat/git_remote_branch

• Mailing list: groups.google.com/group/git_remote_branch

History

git_remote_branch in its current form was inspired by a script created by Carl Mercier and made public on his blog: No nonsense GIT, part 1: git-remote-branch

Contributors

• Mathieu Martin webmat@gmail.com

• Caio Chassot dev@caiochassot.com

• Axelson github.com/axelson

• Carl Mercier github.com/cmer

Legalese

git_remote_branch is licensed under the MIT License. See the file LICENSE for details.

Bleeding edge and development

(Notice the keyword “bleeding”)

Getting the bleeding edge

Installing from GitHub

sudo gem install webmat-git_remote_branch --source=https://gems.github.com

Note that the only stable version of the gem you should trust is the one from Rubyforge. The GitHub gem is a development gem. The GitHub gem WILL be rebuilt with the same version number, and other horrible things like that. If you use the GitHub version of git_remote_branch, children will die! You've been warned.

Cloning the repo and installing from your copy

git clone git://github.com/webmat/git_remote_branch.git
rake install

Testing dependencies

Note that git_remote_branch uses a few more gems for tests. Running any rake task will try to load them due to the way Rake::TestTask works.

sudo gem install thoughtbot-shoulda --source https://gems.github.com
sudo gem install mocha

An attempt is made to require 2 more optional gems: redgreen and ruby-debug. If they're not present, only a whiny message will be displayed.

Supported platforms

git_remote_branch has been tested with the following configurations:

• OS X Leopard / Ruby 1.8.6 / Git 1.5.4.3 and 1.6.0.2

• OS X Leopard / Ruby 1.9.1 / Git 1.5.4.3 and 1.6.0.2

• Ubuntu Intrepid Ibex / Ruby 1.8.7 / Git 1.5.6.3

• Windows XP / Ruby 1.8.6 / Git 1.6.0.2 (the msys version)

Let me know if you have problems running git_remote_branch with your platform.

To run the test suite using Ruby 1.9, simply set the RUBY environment variable to point to your 1.9 interpreter and then run the 1.9 version of Rake. In my case, everything 1.9 is suffixed with 1.9:

$ RUBY=ruby1.9 rake1.9 test

Or on Windows (Ruby 1.9 not tested on Windows)

> set RUBY=ruby1.9
> rake1.9 test