Skip to content
git for humans
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Delete TODO re: prettier Jun 3, 2019
test Fix save docs (#8) Jun 1, 2019
.DS_Store Project management stuff (i.e. editing the docs) Jun 1, 2019
.gitignore Add tests (#4) May 29, 2019
LICENSE Initial commit Apr 17, 2019
README.md
gish Move source files to src Jun 1, 2019
package.json Tweak prettier to work properly on pre-commit Jun 1, 2019
yarn.lock Add prettier (#7) Jun 1, 2019

README.md

gish

git for humans

WARNING: THIS IS HEAVILY IN-DEVELOPMENT. DO NOT USE UNLESS YOU'RE WILLING TO MESS UP YOUR REPO!

The Vision

The current goal is to make git get out of the way and allow work flows that have just a few human-friendly commands like open, switch, save, pr, and merge and rely on upfront configuration (often shared amongst an entire team) for sensible defaults so there's very little data collection needed at command time.

~ $ gish open my-repo-name
Cloned repo https://github.com/steveshaffer/my-repo-name 

my-repo-name $ gish switch 12345 # Where ABC-12345 is a ticket number
Switched to branch feature/ABC-12345 and set ticket [ABC-12345 Users cannot login] status to "In Progress"

# Edit files on disk...

my-repo-name $ gish save "Fix login"
Saved all changes with label "ABC-12345 Fix login" and pushed to GitHub

my-repo-name $ gish pr
Created pull request https://github.com/steveshaffer/my-repo-name/pull/42

Go get the PR reviewed but there were changed requested...

~ $ gish open my-repo-name@12345
Opened ~/projects/github.com/steveshaffer/my-repo-name on branch feature/ABC-12345

my-repo-name $ gish save
Saved all changes with label "ABC-12345 Fix login" and pushed to GitHub

Go get the PR approved...

~ gish open my-repo-name
Opened ~/projects/github.com/steveshaffer/my-repo-name on branch master

my-repo-name $ gish merge 42
Merged pull request https://github.com/steveshaffer/my-repo-name/pull/42

This is possible if we know your...

  • on-disk project directory (e.g. ~/projects)
  • on-disk filing methodology (e.g. ~/projects/github.com/<owner>/<repo>, ~/projects/<repo>)
  • centralized source code hosting platform (e.g. GitHub) and credentials
  • branching methodology (e.g. trunk-based, git-flow, github-flow)
  • ticket system (e.g. Jira, GitHub issues)
  • ticket naming convention (e.g. ABC-12345)
  • commit message convention (e.g. "ABC-12345 ")
  • coordination between ticket system statuses and branching methodology (e.g. In Progress on checkout, Peer Review upon PR, Closed upon merge to master)

The cross-product of the answers to all these questions could be bundled into a "plugin" for gish so we could support all kinds of different work flows from the same core set of commands.

The "gish-flow"?..

The initial flow being supported is an unusual one that's useful for this because it happens to map 1:1 with the core commands. It's something like trunk-based development with a protected master branch and GitHub PRs that are squash-merged. But every commit is also pushed, and the squashing happens continually and forcefully upon every commit so there's only ever 1 commit on the branch/PR.

It forces the reconciliation of conflicts between multiple developers working on the same branch to happen early and often (since commit and push are coupled). And it throws out any concern of a detailed commit history within the branch (since you're just going to squash-merge it anyway).

It relies heavily on checking out detached HEADS, doing hard resets, being super opinionated about the merging strategy, and other things that are fringe enough to not be applicable to many work flows but are common enough to be applicable to a large amount of work flows (at least I hope).

The future hope is that we could also map these core commands to other more standard and complex workflows

Setup

  1. Create a GitHub personal access token at https://github.com/settings/tokens/new and give it the repo scopes.
  2. Write the value of that token into a file called .github/credentials in this repo.
  3. Add the gish command (in this project's root) to your $PATH.

TODOs

  • Make repo owner and name dynamic based on .github/config file
  • Allow for .github/credentials to be defined in any parent directory of this repo
  • Do research on if there's any standards around sharing GitHub credentials through dotfiles
  • Provide a mechanism to interactively collect the necessary credential information and store it (i.e. by asking the user for their username and password once)

Testing

yarn test will run a happy-path script that tries out all the commands. There's no assertions or anything so it's possible for it to run without failure and still be executing incorrectly. Right now it's just a safety net for me as I'm hacking away.

TODOs

  • Use an actual testing framework and stuff

Command Reference

gish switch <branch-name>

Checks out the current version of <branch-name> from origin. If branch does not exist in origin, it creates it off origin/master. Blows out any local copy of that branch that may already exist.

TODOs

  • Check if local copy of branch is ahead of origin. If so, switch to the local copy and inform the user. If not, keep existing logic (which effectively fast-forwards the local copy if it's behind).

gish commit <message>

I'll probably end up deprecating this pretty quickly in favor of gish save (see below)

Commits all changes with the given message

TODOs

  • Auto-prefix the message with the current ticket number (if applicable)
  • Auto-divine the message if none is provided
  • Deprecate in favor of save

gish save [message]

"Saves" local changes to the current branch. If message is provided, it will overwrite the current commit message. If the branch on origin is ahead of the current local copy, it will attempt to automatically merge those. If there are conflicts, it will instruct the user to fix those. At the end of it all, the branch should be in sync with origin and have only 1 commit.

In git terms, it's basically like git add . && git commit -a && git push origin --force if you never had to worry about being out of sync with the remote tracking branch. So there's a good amount of merging, squash-rebasing, and then force-pushing going on here.

TODOs

  • Hone in default/reused messages
  • Auto-merging and conflict resolution stuff
  • Commit descriptions

gish pr <title>

Creates a GitHub PR from the current branch to origin/master.

TODOs

  • Support body
  • Auto-gen a bunch of this stuff
  • Prompt to commit/save if local changes are unsaved?
  • Make STDOUT have a more narrative message by default but configurable to just give the PR ID, number, or URL so it can be called transactionally

gish merge <pr-number>

Merges the GitHub pull request. Assumes squash and merge.

TODOs

  • Better feedback when the merge is not possible and stuff
  • Be able to ID a PR by the ticket number (or title?) or URL
  • Support other methods of merging beyond squash?
  • Delete the branch after merge

Assumptions

  • ./.github/credentials exists and contains a GitHub personal access token as its only non-whitespace content
  • origin is the only remote and represents a GitHub repo
  • master is the integration branch and is not intended to be committed directly to
  • All commits to master are intended to be squashed PR merges

Overall TODOs

  • Get a better name
  • Remove all debugging console.log statements
  • Fix how it runs as a "binary." Should be more standard and able to run with npx
  • Make it into an actual binary with something like pkg.
  • Figure out how to get prettier to run only on staged files during pre-commit hook
  • Convert to TypeScript
  • Build a plugin framework to support various work flows (i.e. trunk-based, github-flow, git-flow, etc.)
  • Build a GUI cuz humans use GUIs
You can’t perform that action at this time.