Programblings

I’m ready to bet that setting up and deleting remote branches is something you do rarely enough that you always find yourself looking up the documentation. Or maybe it’s just me.

Due to its roots, Git supports a wide array of usage scenarios for interacting with remote repositories, and we love it that way. It’s a big factor in the flexibility and power of the tool.

However in simple scenarios, there’s still a bunch of commands you must run to accomplish simple tasks. I believe the commands for the simple scenario can be simpler.

Last January, Carl Mercier created git-remote-branch. I’ve found this script very useful and, with his permission, I’ve decided to keep moving it forward and add a few features to it.

git_remote_branch

The first purpose of git_remote_branch is to encapsulate all the commands that need to be run to interact with remote branches in simple scenarios.

Its second purpose is to be a learning tool. git_remote_branch does two things to help you learn these commands:

•   It clearly displays the commands it runs on your behalf, in a beautiful shade of red;
•   It has an ‘explain’ meta-command that will simply display the list of commands instead of running them for you.

Examples

Help

Let’s start with the simplest of all:

$ grb

or

$ grb help
git_remote_branch version 0.2.2

  Usage:

  grb create branch_name [origin_server]

  grb delete branch_name [origin_server]

  grb track branch_name [origin_server]

  If origin_server is not specified, the name ‘origin’ is assumed (git’s default)

  The explain meta-command: you can also prepend any command with the keyword ‘explain’.
  Instead of executing the command, git_remote_branch will simply output the list of commands
  you need to run to accomplish that goal.
  Example:
    grb explain create
    grb explain create my_branch github

  All commands also have aliases:
  create: create, new
  delete: delete, destroy, kill, remove
  track: track, follow, grab, fetch

As you can see, the syntax for all commands is very regular: action, branch_name and optionally, origin_server.

To facilitate learning even more, aliases are also provided. So to take an example,

$ grb track his_branch

and

$ grb fetch his_branch

are perfectly equivalent.

create

Create lets you create a new branch both remotely and locally. Note that it’s not made to share an existing branch (that feature’s coming).

So what it does is to push your current branch as a new remote branch, then create it locally and track it, for easier pulling afterwards.

$ grb create some_branch
git_remote_branch version 0.2.2

git push origin master:refs/heads/some_branch
Total 0 (delta 0), reused 0 (delta 0)
To /path/to/repo/
* [new branch]      master -> some_branch

git fetch origin

git branch −−track some_branch origin/some_branch

git checkout some_branch
Switched to branch “some_branch”

delete

Presenting features with names that are too self-evident is boring. Let’s get to the point, already.

$ grb delete some_branch
git_remote_branch version 0.2.2

git push origin :refs/heads/some_branch
To /path/to/repo/
- [deleted]         some_branch

git checkout master
Switched to branch “master”

git branch -d some_branch

track

Track lets you easily track the changes that are made to an existing remote branch you’re not tracking already. Each time you pull from the remote repository, the local branch will be automatically merged with the remote branch.

$ grb track his_branch
git_remote_branch version 0.2.2

git fetch origin
From /path/to/repo/
* [new branch]      his_branch -> origin/his_branch

git branch −−track his_branch origin/his_branch

explain

Explain will spew out all commands necessary to accomplish one of the previous actions. There are two ways of using it. The simplest will give you dummy commands:

$ grb explain create
git_remote_branch version 0.2.2

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

Or you can have steps that are tailor-made for what you want to accomplish.

$ grb explain create my_branch github_origin
git_remote_branch version 0.2.2

List of operations to do to create a new remote branch and track it locally:

git push github_origin master:refs/heads/my_branch
git fetch github_origin
git branch −−track my_branch github_origin/my_branch
git checkout my_branch

get git_remote_branch

(Hey, this title has a nice ring to it)

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

Now with rubygems 1.2.0 out (don’t do it with a prior version), you can also add GitHub as a permanent source for your gems:

sudo gem sources -a http://gems.github.com

Now and ever after, you will be able to get anything from GitHub with a simple

sudo gem install webmat-git_remote_branch

If in your eagerness you’ve added github as a source before running

sudo gem update −−system

Please refer to What to do when gems.github.com breaks gems FOREVAR

Look ma, no tests!

Uhhhh, yeah, I know…

This tool is still extremely early in its life and - dare I say it - it’s only hand-tested for now. I’ve been using it personally for a while and it’s working very well for me, if that means anything :-)

So this is still a quick script, only now it has lipstick.

This software should be considered an early version of a pre-alpha. You’ve been warned!

If this makes you queasy, there’s always the ‘explain’ command that can act as your cheat sheet without actually having grb run the commands on your behalf.

For the extra queasy, well you can find the commands very easily without running grb. Just point your favorite editor to lib/git_remote_branch.rb. All commands are there, at the beginning of the file.

For the brave, try it out and tell me what you think. Improvements, bug reports and contributions are all welcome.

And remember, in case of an emergency, you can always refer to my illustrated guide to recovering lost commits with Git ;-)

Here’s what’s to come:

• lots of tests
• a ‘remotize’ functionality (for existing local branches)
• a much better resilience to use in faulty situations (e.g. deleting something that’s not present locally or remotely)
• the possibility to specify different branch names locally vs remotely
• slap an open source licence on it all
• and so much more!