Shell Ruby
Clone or download
Failed to load latest commit information.


Various extensions to git, documented below.

Install git-story

curl -L | bash

The above command will install and inject an import of the git-story script to either .bash_profile, .bashrc or .zshrc (in that order). See install script for details.

Reload your shell to initialize git-story extensions.

Getting started

Branch model:

  1. Start developing a feature, and name it git feature <name>
  2. Save local changes and sync with remote git finish
  3. Create a pull request

The principle is that you develop each new feature in its own branch and when you're done you push it and create a pull request. See GitHub flow branch model. Note that git feature and git finish are flexible. They both take an optional argument target-branch, which the current/new branch will sync with.


$ git feature branch-name   # Sets up clean workspace based on remote master.
$ git finish              # Commit changes, updates current and local branch.

Output example (video).


Print command usage:

$ git <git-story-extension> --usage

Branching extensions

  • Start developing a feature

    $ git feature <branch-name> <target-branch>

    this will create a new branch branch-name based of master or specified target-branch. If the branch exists on remote pull the latest changes. Ensures the uniqueness of branch name at remote. Pushes the created branch to remote. Executes:

    1. Checkout target-branch
    2. Pull target-branch
    3. Create new branch branch-name
    4. Push branch-name
  • Commit and sync with repository

    $ git finish <target-branch>

    commit the changes you've made and merge changes with target-branch. target-branch is optional and the default is target-branch. Executes:

    1. Prompt commit message if any uncommitted changes
    2. Pull current branch
    3. Pull target-branch
    4. Push current branch
    5. Perform local merge with target-branch if configured will exit and print conflicted files if any merge conflicts are found.
  • git branch-status shows current branch status.

  • git pull-branch pull current, or specified, branch's remote changes.

  • git create-branch create and checkout a new branch and push to remote.

  • git push-branch push the current branch to remote.

  • git delete-branch delete branch from remote and local.

  • git delete-merged delete all merged branches locally and at remote.

Convenience extensions

  • git addcom add all files and commit.
  • git fuckit commit all files and push current branch. Default is to prompt for commit message.
  • git redo-commit redo last commit.
  • git goto <branch-name> switches to branch branch-name if the working directory is clean.
  • git abort-merge aborts current merge.
  • git obliterate remove file from local repository and its entire history.
  • git zip-project create zip-file of project.
  • git ignore add and list patterns to local and global gitignore.
  • git ignore-boilerplate easy access to gitignore boilerplates from
  • git conflicted list files with merge-conflicts.
  • git todos list all TODOS and FIXMES.
  • git tag-release create a new tagged release.
  • git rename-tag rename an existing release.
  • git changelog print change log from last tag.
  • git squash-commits squash given number of commits together.

Log extensions

  • git history view repository commit history.
  • git trail shows the last common commit with current branch.
  • git neck show commits until first branching point.
  • git divergence show the difference between current branch and the same branch at remote.
  • git local-commits show local commits that haven't been pushed to remote.
  • git commits-since show commits since given time.

Project integration extensions

  • git browse opens the repository on GitHub.
  • git package package project, runs GS_PACKAGE.
  • git deploy package project, runs GS_DEPLOY.
  • git install-project install project, runs GS_INSTALL.
  • git test package project, runs GS_PRE_COMMIT_HOOK.
  • git tag-release tags release, runs GS_TAG_RELEASE.

Statistics extensions

  • Show statistics for repository

      git stat <type>
        contrib <name> # shows statistics for all or specified author (alias: contributions)
        commits        # shows number of commits for each author
        weekdays       # prints statistics for number of commits per weekday
        hour           # prints statistics for number of commits per hour
        files          # prints number of files and lines
        diff           # Print stat of uncommitted changes
        log            # Print log with stat
        modified       # Print stat of most modified files

    prints statistics of given type.

  • git churn count number of changes for each file.

  • git effort like churn, but prettier and with active day count.

  • git summary show summary for current project.

git-story interactions

  • git gs-update gets the latest version of git-story.
  • git gs-extend <extension-name> add new git-story extension to git.
  • git gs list git-story extensions.


  • git repl git read-eval-print-loop (REPL).


Configure git-story by creating a file ~/.gitstoryrc For project specific configurations create a file named .gitstoryrc at the project's git root.

See full example with comments in docs/gitstoryrc-example.

Available options and their default value:

GS_DEFAULT_REMOTE='origin'          # Default remote for git story
GS_GIT_STORY_BRANCH='master'        # Target branch for 'feature' & 'finish'
GS_LOCAL_MERGE=false                # Perform local merge on 'finish'
GS_PRINT_CHECKLIST=false            # Print checklist before 'finish'
GS_GRAPHIC_PROMPT=false             # Show all prompts (on OSX) in a GUI dialog
GS_PROMPT_ON_DONE=false             # Prompt user before 'finish'
GS_TEST_ON_DONE=true                # Run test command before 'finish'
GS_SIGN_RELEASE=true                # Sign tags created with 'tag-release'
GS_SIGN_COMMITS=true                # Sign each commit created with addcom, with GPG-key
GS_SIGN_COMMITS_STRING=true         # Sign each commit created with addcom, with --signoff
GS_CHECKLIST_MESSAGE='...'          # Checklist string for 'finish'
GS_PRE_COMMIT_HOOK=''               # A command that runs all tests
GS_PACKAGE=''                       # Shell command for 'package'
GS_DEPLOY=''                        # Shell command for 'deploy'
GS_TAG_RELEASE=''                   # Shell command for 'tag-release'
GS_INTSALL=''                       # Shell command for 'install'
GS_HAS_GITHUB=true                  # Project has GitHub.
GS_PROJECT_URL=''                   # Project URL
GS_TEST_ON_AUTO_MERGE=true          # Run tests command on auto merge
GS_PRODUCTION_BRANCH='heads/master' # Integration branch for production
GS_NEXT_VERSION_BRANCH=''           # Integration branch for next
GS_EDGE_BRANCH=''                   # Integration branch for edge
GS_GIT_STORY_EXT_BRANCH='master'    # Target branch for git-story extension


  • The software is supplied “as is” and all use is at your own risk (see license)
  • git branch-status requires Ruby 1.8.7 or greater
  • Tested on Linux/OSX/Windows using both zsh, bash and cygwin*, doesn't work with sh.
  • Almost everything works with cygwin except:
    • git trail
    • git neck both neck and trail fails on git -p column
  • Fork the repository and update the URL defined in setup/install to install and use your own version of git-story
  • Thanks:
  • Uninstall git-story: rm -rf ~/.git-story


git-story is released under the MIT License.