Make your own Git subcommands

Git is pretty famous for having lots of subcommands, like clone, init, add, mv, restore, bisect, blame, show, rebase, and many more. In a previous article, I wrote about the very useful rev-parse subcommand for Git. Even with all of these subcommands available, users still come up with functions to improve their Git experience. While you're free to create Git-related commands and run them as scripts, it's easy to make your own custom Git subcommands. You can even integrate them with Git through rev-parse.

Create a simple Git script

A script that integrates with Git can be as complex as you need it to be, or it can be short and straightforward.

As a simple example, assume you've created a script that gathers the file names of your latest commit and places them into a file called latest.txt. You use this script after every commit for reporting purposes, and you've decided it would be handy to be able to run the script as if it were a built-in feature of Git, for instance, with the command git report.

Currently, running git report renders this error:

$ git report
git: 'report' is not a git command. See 'git --help'.

The most similar command is
        bugreport

Here's the script that generates your report:

#!/bin/sh

TOP=$(git rev-parse --show-toplevel)
HASH=$(git log --pretty=format:'%h' -n 1)

mkdir "${TOP}"/reports || true

git diff-tree \
--no-commit-id --name-only \
-r HEAD > "${TOP}"/reports/$HASH

Save this file as git-report.sh somewhere in your PATH.

You're not going to run this script directly, so do include the .sh extension in the name. Make the script executable:

$ chmod +x git-report.sh

Create the front-end command

You can force Git to run git report through rev-parse and launch your git-report.sh script instead of returning an error. Here's the script:

#!/bin/sh

git-report.sh

Save this file as git-report (do not use a .sh file extension) somewhere on your PATH. Make the script executable:

$ chmod +x git-report

Running your custom Git command

Now test it out. First, create the infrastructure and some sample data:

$ mkdir myproject ; cd !$
$ git init
$ echo "foo" > hello.txt
$ git add hello.txt
$ git commit -m 'first file'
$ git report

Look inside the reports directory to see a record of your latest commit:

$ cat reports/2e3efd8
hello.txt

Pass arguments to your script

You can pass arguments through rev-parse, too. I help maintain a Git subcommand called Git-portal, which helps manage large multimedia files associated with a Git repository.

It's a little like Git LFS or Git Annex, except without the overhead of versioning the actual media files. (The symlinks to the files are kept under version control, but the contents of the files are treated independently, which is useful in scenarios where the artistic process is distinct from the development process.)

To integrate Git-portal with Git as a subcommand, I use a simple front-end shell script, which in turn invokes rev-parse for literal parsing.

The example script provided in this article can't take any parameters, but the actual Git scripts I write almost always do. Here's how arguments are passed, for example, to Git-portal:

#!/bin/sh

ARG=$(git rev-parse --sq-quote "$@")
CMD="git-portal.sh $ARG"
eval "$CMD"

The --sq-quote option quotes all arguments following git portal and includes them as new parameters for git-portal.sh, which is the script with all the useful functions in it. A new command is assembled into the CMD variable, and then that variable is evaluated and executed.

Here's a simple example you can run. It's a modified version of a script I use to resize and apply accurate copyright (or copyleft, as the case may be) EXIF data to images for a flat-file CMS I use Git to manage.

This is a simplified example, and there's no good reason for this script to be a Git subcommand, but it's demonstrative. You can use your imagination to find ways to expand it to use Git functions.

Call this file git-imager.sh:

#!/bin/sh
## Requires
# GNU Bash
# exiftool (sometimes packaged as perl-Image-exiftool)
# Image Magick

PIC="${1}"
COPY="-Copyright"
LEFT="${2}"

mogrify -geometry 512^x512 -gravity Center \
        -crop 512x512+0+0 "${1}"

exiftool -Copyright="${2}" "${1}"

The front-end script for Git integration passes all parameters (the file name and the license) through to the git-imager.sh script.

#!/bin/sh

ARG=$(git rev-parse --sq-quote "$@")
CMD="git-imager.sh $ARG"
eval "$CMD"

Try it out:

$ git imager logo.jpg "Tux CC BY-SA"
 1 image files updated

Easy Git customization

Creating your own Git subcommand makes your custom scripts feel like natural components of Git. For users, it makes the new subcommands easy to remember, and it helps your subcommands integrate into the rest of everyone's Git workflow.