buren / git-story

Simplified git workflow.

git-story

Various extensions to git, documented below.

• Installation
• Getting Started
• Example
• Configuration
• Documentation
  • Branching extensions
  • Convenience extensions
  • Log extensions
  • Project integration extensions
  • Statistics extensions
  • git-story interactions
  • Misc
• Notes
• License

Install git-story

curl -L https://raw.githubusercontent.com/buren/git-story/master/setup/install | 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.

Example

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

Output example (video).

Documentation

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 github.com/github/gitignore.
• 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>
  
    types:
      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.

Misc

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

Configuration

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

Notes

• 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:
  • visionmedia/git-extras
  • cypher/dotfiles
  • simonwhitaker/gibo
• Uninstall git-story: rm -rf ~/.git-story

License

git-story is released under the MIT License.

git-story's Issues

Add git-trash

https://github.com/henrikpersson/git-trash

Remove printing of gs-ready-help on error in gs-ready

Confusing... Remove!

__gs-ready-execute pull current branch conflict

If the current local branch has remote changes potential merge conflicts for the local branch is currently not implemented.

A check should be made that automatic merge was successful for the local branch before pulling from target_branch

https://github.com/buren/git-story/blob/master/src/git_story.sh#L412

Find and refactor duplicated code

Research what method is best to use for creating stable reusable code. Nvie's gitflow could be a good example of clean code

Could git interactive staging be added?

Git Tools - Interactive Staging
Enables an interactive guide to adding files one by one. (Could perhaps be put together with a commit to make it easier?)

Add pull-current command

Add pull-current command, which pulls the current command

• Fetch and merge

  git pull-current
  

  fetch and merge from remote.
  Example: If the current branch is "test_feature" it will try to fetch and merge the remote version of test_feature.

Add command to push current branch

Add git recent-branches

http://ses4j.github.io/2020/04/01/git-alias-recent-branches/

Improve outputs and error handeling

Test all commands and suppress unnecessary output.

Work through each method and try to find unhandled errors/states.

Auto generate README.md and docs

gs open does not work on Linux

Since the command calls open which Linux doesnt undestands. Add if clause to check is on linux or osx.

if linux

xdg-open

Add CLI command to fetch all remote branches

There are already a private function __gs-fetch... that does this. Need only to add command to cli.sh

Cygwin: git browse does nothing

make git browse play nice with cygwin:
cygstart "http://www.example.com";

Wrong output on "gs" usage outside of a git folder

Add 'todos' and 'fixmes' extensions.

Add extensions which lists all 'TODO' and 'FIXME' in project.

Add separate gs release command

Remove GitHub merge commits from changelog commands

Filter git changelog --list output through grep and remove all merge commits.

Example:

Merge pull request #XX from user/branch

On gs dev

on ´gs dev´ prompt if dirty working set. Would you like to continue?

Enable config options for running tests before 'git feature'

Enable a config options so that when running git feature it could run all tests in-order to verify what state the base branch had.

Combine add and commit to add-commit

Add command add-commit which does

cd $to_git_root
git add --all
git commit -m "$1"

gs reset

Should reset 'gs dev' command, after prompting the user "Are you sure?"

set -e (exit on failed command)

Make script exit if any command fail.

Check what statuses git sends on error.

Add install project integration commando

'gs test' like commando but for 'gs install' (which install/setup the project)

Prompt user on uncommitted changes rather than exit

Prompt user on uncommitted changes and ask if they'd like to continue anyway

Wrong output on 'gs pull' / 'gs dev' on merge conflict

Currently the commands outputs "No such branch" even though its a merge conflict.

Extend git directly rather than through gs

The public function gs could be renamed to git and handle all "known" inputs and then forward all others to git "$@"