$ twig

                              issue  status       todo            branch
                              -----  ------       ----            ------
2013-01-26 18:00:25 (7m ago)  486    In progress  Rebase          optimize-all-the-things
2013-01-26 16:49:47 (2h ago)  268    In progress  -               whitespace-all-the-things
2013-01-23 18:35:12 (3d ago)  159    Shipped      Test in prod  * refactor-all-the-things
2013-01-22 17:12:23 (4d ago)  -      -            -               development
2013-01-20 19:45:54 (6d ago)  -      -            -               master

It’s hard enough trying to remember the names of all of your Git branches. You also need their issue tracker ids, issue statuses, and reminders of what to do next with each branch. git branch just isn’t cutting it.

Twig shows you your most recent branches, and remembers branch details for you. It supports subcommands, like automatically fetching statuses from your issue tracking system. It’s flexible enough to fit your everyday Git workflow, and will save you a ton of time.

Quick start


$ gem install twig

$ twig init  # Set up tab completion (Running this once
             # works across all repos)

$ twig       # List your branches, newest first

$ twig help  # More info

Usage

Here are the most common uses:

twig
List all branches with properties, newest first
twig --max-days-old 30
Only list branches modified in the last 30 days
twig <property>
Get a custom property for the current branch
twig <property> <value>
Set a custom property for the current branch
twig --unset <property>
Unset a custom property for the current branch
twig help
See more options

For example, remember a branch’s issue tracker id like this:


$ git checkout my-branch
Switched to branch 'my-branch'.

$ twig issue 123
Saved property "issue" as "123" for branch "my-branch".
# Nearly any property name will do, like "bug" or "ticket".

$ twig issue
123

$ open "https://github.com/myname/myproject/issues/`twig issue`"
# Opens a browser window for this GitHub issue (in OS X).

Keep notes on what you need to do with each branch:


$ twig todo "Run tests"
Saved property "todo" as "Run tests" for branch "my-branch".

$ twig todo "Deploy" -b finished-branch
Saved property "todo" as "Deploy" for branch "finished-branch".

$ twig

                              todo         branch
                              ----         ------
2013-01-26 18:00:25 (7m ago)  Run tests  * my-branch
2013-01-23 18:35:12 (3d ago)  Deploy       finished-branch
2013-01-22 17:12:23 (4d ago)  -            master

Remember the order in which you were rebasing your stack of branches:


$ git checkout master
Switched to branch 'master'.

$ twig diff-branch branch2 -b branch3
Saved property "diff-branch" as "branch2" for branch "branch3".

$ twig diff-branch branch1 -b branch2
Saved property "diff-branch" as "branch1" for branch "branch2".

$ twig

                              diff-branch    branch
                              -----------    ------
2013-01-26 18:00:25 (7m ago)  branch2        branch3
2013-01-26 16:49:47 (2h ago)  branch1        branch2
2013-01-23 18:35:12 (3d ago)  -              branch1
2013-01-22 17:12:23 (4d ago)  -            * master

You can set just about any custom property you need to remember for each branch.

Twig lists all of your branches by default (newest first), but you can filter them by name, age, and your own custom properties. To learn more, run twig help or read the Twig docs.

Subcommands

A Twig subcommand is a little script that makes use of a branch’s Twig properties. You can write your own, but here are some subcommands that Twig comes with.

twig checkout-child

Twig uses each branch’s diff-branch property to remember its parent branch so you don’t have to. If you need to check out one of the child branches for your current branch, you can use twig checkout-child: 


$ git checkout feature-branch

# Look for any branch whose `diff-branch` property is
# `feature-branch`, and checkout that branch:
$ twig checkout-child

# If the current branch has multiple child branches,
# Twig asks what to do:
Checkout which child branch?
  1. child-branch-1
  2. child-branch-2
  3. child-branch-3
> 3
Switched to branch 'child-branch-3'

More advanced usage:


# Switch to a child branch of any other branch:
$ twig checkout-child -b other-feature-branch
Switched to branch 'other-child-branch'

You can use this with twig checkout-parent and twig create-branch to traverse your tree of branches.

twig checkout-parent

If your branch has a diff-branch property, you can use twig checkout-parent to quickly switch to that branch: 


$ git checkout branch2

# Remember your branch's diff branch:
$ twig diff-branch branch1
Saved property "diff-branch" as "branch1" for branch "branch2".

# Later, switch from branch2 (the current branch) to
# its parent branch:
$ twig checkout-parent
Switched to branch 'branch1'

More advanced usage:


# Switch to the parent branch of any other branch:
$ twig checkout-parent -b other-branch-2
Switched to branch 'other-branch-1'

You can use this with twig checkout-child and twig create-branch to traverse your tree of branches.

twig create-branch

When creating a branch, you can use twig create-branch to create a child branch and set its diff-branch property automatically: 


$ git checkout master
$ twig create-branch my-branch
Branch my-branch set up to track local branch master.
Switched to a new branch 'my-branch'
Saved property "diff-branch" as "master" for branch "my-branch".

# Confirm that the new branch's `diff-branch` is its parent:
$ twig diff-branch
master

# Check out the new branch's parent:
$ twig checkout-parent
Switched to branch 'master'

You can use this with twig checkout-child and twig checkout-parent to traverse your tree of branches.

twig diff

If you have a stack of branches with different parent branches, it gets tricky to remember which branch to diff against. twig diff makes it easy: 


$ git checkout branch2

# Remember your branch's diff branch:
$ twig diff-branch branch1
Saved property "diff-branch" as "branch1" for branch "branch2".

# Generate a diff between branch1 (the current branch) and branch2:
$ twig diff

More usage:


# Generate a diff between any given branch and its `diff-branch`:
$ twig diff my-other-branch

# Pass options through to `git diff`:
$ twig diff --stat

# Pipe results to a diff viewer:
$ twig diff | gitx

twig rebase

If you have a stack of branches that you need to rebase in the same order every time, twig rebase simplifies the process: 


$ git checkout branch2

# Remember your branches' diff (parent) branches:
$ twig diff-branch branch1
Saved property "diff-branch" as "branch1" for branch "branch2".

# Rebase branch2 (the current branch) onto branch1:
$ twig rebase
Rebase "branch2" onto "master"? (y/n) y

More usage:


# Rebase any given branch onto its `diff-branch`:
$ twig rebase my-other-branch

# Pass options through to `git rebase`:
$ twig rebase -i

twig gh-open

While inside a Git repo, run twig gh-open to see the repo’s GitHub URL, and open a browser window if possible: 


$ cd myproject

$ twig gh-open
GitHub URL: https://github.com/myname/myproject
# Also opens a browser window.

twig gh-open-issue

For any branch that has an issue property, you can use the gh-open-issue subcommand to view that issue on GitHub: 


# Current branch:
$ twig gh-open-issue
GitHub issue URL: https://github.com/myname/myproject/issues/111
# Also opens a browser window.

# Any branch:
$ twig gh-open-issue -b <branch name>
GitHub issue URL: https://github.com/myname/myproject/issues/222

twig gh-update

If you’re working on an issue for a GitHub repository, the gh-update subcommand syncs issue statuses with GitHub: 


$ git checkout add-feature
Switched to branch 'add-feature'.

$ twig issue 222
Saved property "issue" as "222" for branch "add-feature".

$ twig

                              issue  status    branch
                              -----  ------    ------
2013-01-26 18:00:25 (7m ago)  222    -       * add-feature
2013-01-23 18:35:12 (3d ago)  111    -         fix-bug
2013-01-22 17:12:23 (4d ago)  -      -         master

$ twig gh-update
Getting latest states for GitHub issues...
# Automatically looks up the GitHub issue status for each
# of your local branches, and saves it locally.

$ twig

                              issue  status    branch
                              -----  ------    ------
2013-01-26 18:00:25 (7m ago)  222    open    * add-feature
2013-01-23 18:35:12 (3d ago)  111    closed    fix-bug
2013-01-22 17:12:23 (4d ago)  -      -         master

Run twig gh-update periodically to keep up with GitHub issues locally.

You can write any Twig subcommand that fits your Git workflow. Some ideas:

To learn how to write a Twig subcommand, check the Twig docs. If you write one that others might appreciate, send a pull request or add it to the Twig wiki!

More info