⚠️ Notice of Proposal - click to read

👋 G'day! Thanks for checking out my project. This is a note to let you know the current official status of this project is 'proposed'. Development is probably underway in the alpha branch by now, but please be aware that anything you read below is written solely as a goal state to help guide development.

What does this mean for you? In short, it probably won't work for you ... yet!

If you like the proposal though, please show your support by starring and watching the repo to receive alerts as development progresses. Developers are welcome to check out the other branches to see the progress directly and may even make contributions if they are feeling brave enough!

 

 

There are already a LOT of collections of git tools and aliases out there. Here lies another.
_{Give your git workflow superpowers with this meticulously curated collection of extra git commands, related software and some cool aliases and functions for good measure. This project has several ambitious goals. One of the most noteworthy is to make cross provider support easier by bringing the power of gh, tea, jira, glab and others back into a standard interface under git itself.}

🎯   Goals

• Cross platform support:
  • Git repository hosting platforms: Github (inc. Enterprise), Bitbucket, Gitea and Gitlab
  • Operating systems: Linux, macOS and Windows (via Git Bash)
• Prioritise use of a central git root directory where all projects live with tooling to make working within it easier (akin to go get)
• Manage multiple git identities - keep work and personal life separate
• Add convenience functions, utilities and mnemonics
• Install common extensions automatically

🙅   Non-goals

• Short aliases like alias g=git and alias gc=git commit
  • Everyone tends to have very individual preferrences, so you're better off managing them in your own dotfiles
  • Some functions that could be used as global aliases have been created, but won't be aliased by default - i.e. check out the gud-gg script for which a lazy programmer might add alias gg=gud-gg to their dotfiles
• Anything that is going to really mess up common workflows
• Mandating ways of working within git repos (i.e. this won't force git flow on you)

  Click heading to show / hide

📖   Table of contents

• 🎯   Goals & Non-goals
• 📖   Table of contents
• ⌛️   Quick start
• 🧠   Philosophy
• 😱   Extended commands
• 🧭   Repo management
  • ➤ Repos
  • ➤ Users
  • ➤ Remote
  • ➤ Workflow
• New commands
  • ➤ Utilities
  • ➤ New verbs
  • ➤ New namespaces

⌛️   Quick start

🤷‍♂️ Probably ZSH plugin is the fastest way for those who wanna try it. I guess I will need to implement that.

Otherwise...

1. Clone project
2. Add ./bin to path
3. Include ./git-gud-aliases in ~/.gitconfig
4. git gud install

... will be the likely workflow

🍺 Homebrew support is a probably a good idea as well

🧠   Philosophy

Git is a very powerful but complex piece of software. It is natural to want to make something complex easier to use.

I am slightly wary that Microsoft is setting up to roll out their E3 business strategy again with the gh tool. This is an effort to comodotise Github again and fight back against it becoming a massive walled garden.

To reduce cognitive overload, the following decision framework was made:

• Extend builtin commands where practical
• Limit the number of new subcommands

This allows better scripting options and makes it easier to work in the terminal without having to worry about where the project is actually hosted (you know, because decentralised and standardied was the goal of using git in the first place).

The developer only needs to remember a handful of extra things to get the most from this package:

1. You can check if any built command has any superpowers by running it with --superpowers
2. Remote git repo hosting platforms are managed in git now, and done in a fairly intuitive manner. Things like git pr work as expected for example.

😱   Extended commands

Git Gud uses the git-extend project to extend the built in commands of git. This may cause some potential users of Git Gud to scream in disgust and run away. I encourage you to try it out though ... then you can run. Every effort has been made to keep it as seemless as possible without causing any breaking changes to existing workflows.

ℹ️ Once Git Gud is installed, explore what changes have been made by appending --goodies, --superpowers, --extras or --helpers to any built in command. (it must be the first parameter to work, i.e. git show --goodies). If git complains about invalid arguments/usage, the command has not been extended. Otherwise helpful information will be displayed.

Click to show the list of butchered supercharged commands ...

git add

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git branch

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git checkout

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

Incorporate from git-extra-commands:

• git-checkout-branches
• git-checkout-by-date
• git-checkout-default-branch

git diff

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git log

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git merge

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

Incorporate from git-extra-commands:

• git-improved-merge

git pull

🚧 Coming soon

Incorporate from git-extra-commands:

• git-superpull

git push

🚧 Coming soon

Incorporate from git-extra-commands:

• git-sp - add as a flag to built in push (maybe also add git sp as an alias?)

git reflog

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git rm

🚧 Coming soon

Incorporate from git-extra-commands:

• git-submodule-rm
• --clean - git-rm-deleted-from-repo
• --dangling-commits - git-delete-dangling-commits
• --local-merged - git-delete-local-merged
• --merged-branches - git-delete-merged-branches
• --remote-branch - git-delete-remote-branch
• --squashed-and-merged-branches - git-delete-squashed-and-merged-branches
• --tag - git-delete-tag

Add a --nuke flag that totally destroys the object both locally and remotely:

🚨 Very destructive!

• --nuke
  • repo
  • branch - git-nuke
  • file - git-purge-from-history
  • local - git-reset-with-fire

git show

🚧 Coming soon

Useful functions to provide insights into the repo you are working in

Incorporate from git-extra-commands:

• git show - show various useful data
  • --big-files
  • --branches-that-touch
  • --changes - git-what-the-hell-just-happened
  • --children-of-commit
  • --churned-files - git-churn
  • --commit-in-release - git-where
  • --common-ancestors - git-oldest-common-ancestor
  • --conflicts - git-conflicts
  • --default-branch - git-remote-default-branch
  • --divergence
  • --ignored - Files in the repo being ignored because of .gitignore
  • --incoming - git-incoming
  • --last-diff
  • --neck - git-neck (counterpart to --neck)
  • --outgoing - git-outgoing
  • --recent-changes - git-recent
  • --recently-checkedout-branches - git-recently-checkedout-branches
  • --related - git-related
  • --relationship - git-rel
  • --trail - git-trail (counterpart to --neck)
  • --unreleased - git-unreleased
  • --unpushed - git-unpushed
  • --when-merged - git-when-merged

git stash

🚧 Coming soon

Make it behave a bit nicer - see @MisterRios/stashy

git status

🚧 Coming soon

Will have whatever the boilerplate provided by git-extend supplies to start with.

git tag

🚧 Coming soon

Incorporate from git-extra-commands:

• git-tag-diff as --diff
• git-tag-and-sign - can we autosign based on profile?

git undo

🚧 Coming soon

Incorporate from git-extra-commands:

• git-undo
• git-undo-push
• git-undelete

🧭   Repo management

AKA: Universal git repository hosting platform management

These commands are designed to provide a standard interface to a number of platform specific tools. Running git gud install will ensure the needed dependencies are also installed to make this work seamlessly. This includes: gh, tea, jira, glab

➤   Repos

These commands help the developer get existing repositories from the supported platforms, and helps them navigate faster.

git get

• git get - ghq alias (with some conveniences added)

git go

• git go - cd to repo directory

git open

• git open - open repo/file/pr/commit/issue in browser (alias as git browse as well)

Other related functions

• gud gg - smarter combination of git get, git go and git open; useful to alias to gg

Supported platforms

Command	Github	Bitbucket	Gitea	GitLab
get	﹖	﹖	﹖	﹖
open	﹖	﹖	﹖	﹖

➤   Users

Manage which credentials and identities work wiith which providers using these tools

git profile

• git profile - Create or manage user profiles
  • auth
  • config
  • email
  • gpg
  • name
  • select
  • ssh

git whoami

• git whoami - show user.name <user.email> based on the repo you are. Also show profile information

Supported platforms

Command	Github	Bitbucket	Gitea	GitLab
profile	﹖	﹖	﹖	﹖

➤   Remote

All the things that make git a truly collaborative experience are here

git issue

• git issue - Create or manage issues

git pr

• git pr - Manage PR in CLI or open PR in browser
  • Create a draft PR

git publish

• git publish - see git-publish for inspiration

git release

• git release -

git topic

• git topic - Change the topic on the repo page

Supported platforms

Command	Github	Bitbucket	Gitea	GitLab
issue	﹖	﹖	﹖	﹖
pr	﹖	﹖	﹖	﹖
publish	﹖	﹖	﹖	﹖
release	﹖	﹖	﹖	﹖
topic	﹖	﹖	﹖	﹖

➤   Workflow

Tools that come under the development workflows

git dev

• git dev - Startup dev workflows (local and remote)

git gist

• git gist -

git tasks

• git tasks - Github Actions (gh workflow / gh run), CI, etc

Supported platforms

Command	Github	Bitbucket	Gitea	GitLab
dev	Codespaces	﹖	﹖	﹖
gist	✅	﹖	﹖	﹖
tasks	Actions	﹖	﹖	﹖

🧑‍💻   New commands

Git Gud adds a number of extra subcommands to your local git installation.

➤   Namespaced

git author

Very useful for blaming or thanking authors, as well as for trying to figure out who can help with a problem.

Some of these might be flags. Will need to plan how to make it all work as a unified command that matches the rest of the git DX.

• git author
  • change - git-change-author, git-replace-author
  • credit - git-credit
  • contributions - git-rank-contributors
  • current - List current authors in the repository in descending commit-count order. git-authors
  • historic
  • mvp - Top 10 authors by number of commits and by number of lines changed git-winner
  • wordy - Sort authors by commit message length git-wordiness

git ui

Run different commands using a terminal-based GUI (TUI) instead of the command line.

Supported packages:

• GitUI
• lazygit
• tig

Supported actions:

• git ui - Open repo in terminal UI
  • add
  • commit
  • ?

git utils

A collection of useful functions that are used with git.

It's recommended to alias gu to git utils since there is limited subcommands in git starting with 'u'.

• git utils
  • git ignore - git-make-gitignore
  • git io - Generate git.io short URLs (proposed: add support for custom url shortners)
  • git replay - scrub through git commits, forwards and backwards (see git-jump)
  • git summary - prettier git status (see git wtf)

➤   Verbs

git ls

List various objects in a number of ways.

• git ls (suggested aliases ls and ll)
  • branch - git-branch-status, git-current-branch
    • --upstream - git-upstream-name
  • commit - git-current-commit
    • --merged - git-merged-branches
  • diff - partially inspired by the idea of git-maildiff, but for piping into clip or similar
  • files - builtin git ls-files
    • --deleted - git-attic
  • remote - builtin git ls-remote
  • repo
    • --default-branch git-origin-head
  • root - echo global project root(s) (via ghq) or root of current repo (git-root-directory, with --local flag)
  • tags - git-tags, git-taglist
  • tree - builtin git ls-tree
  • stats - print summary of changes (for prompt/status bars)
    • --oneline - put them all on one line

Options:

• --longlist -l - show extra information
• --pretty - print in colour and with Nerd Font icons (useful for $PROMPT/$PS1 in conjunction with --limit=1)
• --limit=n - just get n item(s)
• --format=json - option to get data in json to pipe into jq

git new

• git new (also alias create)
  • repo will also initialise it and push to remote
  • branch
  • orphan

git search

• git search - Fuzzy find things (using fzf)
  • commit - git-commit-browser
  • checkout - git-checkout-commit, git-checkout-preview
  • add - git-fzf-add
  • log - git-fzf-log-browser, git-fzf-pickaxe-browser
  • reflog - git-fzf-reflog-browser
  • switch - git-sr

➤   Functions

These subcommands are convenience functions. They are wrappers around other commands, usually with the intention of turning multi-step workflows into one command.

New subcommands like these should be added very sparingly to avoid polluting the global namespace and to avoid adding to the developers cognitive workload. In some cases though, it makes sense to bring some functionality to the top level of git, escpecially for workflows that are performed several times a day.

• git alias - List available aliases (--help flag will print config.help.aliasname and config.usage.aliasname)
• git co - git checkout if a branch is named (also incorporate git-switch-branch), else start a fzf branch chooser
• git git - Fix common typo (especially when copy and pasting commands)
• git unstage - @LucasLarson/gunstage
• git sync - combination of git-upstream-sync, @caarlos0-graveyard/zsh-git-sync and @washtubs/gitsync

🔋   Included extensions

• git gud
  • update
  • install
  • completion
• git lfs - Large File Storage
• git secret - @sobolevn/git-secret
• git time - Time tracking integration

References & Inspiration

• https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases

Unholy list of ZSH plugins for git

TODO: Curate these

• @alexiszamanidis/zsh-git-fzf
• @aswitalski/oh-my-zsh-opera-git-plugin
• @aubreypwd/zsh-plugin-git-is-clean
• @bigH/git-fuzzy
• @buzuloiu/zsh-github-folders
• @caarlos0-graveyard/git-add-remote
• @caarlos0-graveyard/zsh-git-sync
• @caarlos0-graveyard/zsh-open-pr
• @capsulescodes/more-hooks-for-git
• @dehlen/git-tree-zsh
• @denysdovhan/gitio-zsh
• @diazod/git-prune
• @egyptianbman/zsh-git-worktrees
• @git-time-metric/gtm-terminal-plugin
• @gobriansteele/git-clean-branch
• @grimmbraten/gitgo
• @jelek21/omz-git-smart-commands
• @laggardkernel/git-ignore
• @ltj/gitgo
• @lyze/posh-git-sh
• @mroth/git-prompt-useremail
• @nicolodiamante/gitio
• @packruler/zsh-git-scripts
• @peterhurford/git-aliases.zsh
• @peterhurford/git-it-on.zsh
• @rapgenic/zsh-git-complete-urls
• @rcruzper/zsh-git-plugin
• @robertzk/send.zsh
• @robin-mbg/switch-git
• @Schroefdop/git-branches
• @seletskiy/zsh-git-smart-commands
• @shakir-abdo/zsh-github-plugin
• @SukkaW/zsh-gitcd
• @tevren/gitfast-zsh-plugin
• @unixorn/bitbucket-git-helpers.plugin.zsh
• @viko16/gitcd.plugin.zsh
• @voronkovich/gitignore.plugin.zsh
• @wfxr/forgit
• @xylous/gitstatus
• @ytakahashi/igit

🎗   Contributing

I might sell Git Gud stickers and shirts actually. Could be fun...

🙏 Thanks!

As with any open source project, this one is also built on the good work of others.

➤   Git Gud logo

The Git Gud logo is remixed from the Git Logo by Jason Long under the Creative Commons Attribution 3.0 Unported License. Thanks for giving your awesome design to the open-source community so freely Jason!

Disclaimer: This project is in no way affiliated with or sponsored by the git project, or its' maintainers. This is not in any way an "official" git project.

➤   Joe Blocks

Big thanks to Joe Blocks (@unixorn) and his extra-git-commands project. Most of the foundational work for this project is based of his collection and work.

➤   Inspiration for short aliases

Thanks to the authors of these repositories which I referenced whilst creating my own short aliases for git. These repositories are primarily simple aliases, but there are a few neat functions as well. Hopefully they may inspire you too.

• Oh My Zsh!
• @aswitalski/oh-my-zsh-sensei-git-plugin
• @bossjones/boss-git-zsh-plugin
• @gimbo/gimbo-git.zsh
• @mdumitru/git-aliases
• @MenkeTechnologies/zsh-git-acp
• @sebastiangraz/c
• @zimfw/git
• @nekofar/zsh-git-lfs
• @davidde/git