Sharing Your Tool

A script someone else can use explains itself with --help and --version, comes with a README that says what it does and how to install it, an install script that puts it on their PATH, and a license that says what they may do with it, and GitHub is where people find it.

Journeyman · Unix · Linux · Updated

After this lesson you can

  • Make a script shareable with --help, a --version number, a README and an install script that puts it in ~/bin
  • Explain what a license file and a version number tell the people who use your tool, and the steps to publish it on GitHub

Key takeaways

  • --help says how to use a tool and --version which version it is: the first two things a stranger types.
  • A version number such as 1.0.0 is major.minor.patch: a fix raises the last number, a new feature the middle one, and a change that breaks how people use it the first.
  • A README says what the tool does, how to install it and how to use it, with one example.
  • An install script copies the tool into ~/bin and checks with command -v that its name now works.
  • Without a LICENSE file, others may read your code but have no permission to copy or change it. MIT is a common, short choice.

The bakery's test.sh turns out to be handy: a friend with a hiking club website asks for "that title checker". You send her the file, and the questions start. How do I run it? Where do I put it? It says "permission denied". Am I allowed to change it for my club's site? Everything you know about the script is in your head, and none of it traveled with the file. A tool you share has to answer those questions by itself. The same few pieces make that happen, whether it's a script for one friend or a tool thousands of developers install: the command-line tools you've used in this course, bats and ShellCheck among them, come with every one of them.

The tool explains itself: --help and --version

Make the shareable version, pagecheck, in a folder of its own. It checks any folder you name, and answers --help and --version before anything else, the way Options and Flags: getopts and --help showed:

#!/usr/bin/env bash
# pagecheck: checks that every web page in a folder has a <title>.
version="1.0.0"

case "${1:-}" in
  --help)
    cat <<EOF
Usage: pagecheck [FOLDER]
Checks that every .html page in FOLDER has a <title>.
Leave FOLDER out to check the folder you're in.

  --help      show this help
  --version   show the version number

Exit code 0 when every page has a title, 1 when one doesn't.
EOF
    exit 0
    ;;
  --version)
    echo "pagecheck $version"
    exit 0
    ;;
esac

folder="${1:-.}"
failed=0
for page in "$folder"/*.html; do
  if ! grep -q '<title>' "$page"; then
    echo "No title: $page"
    failed=1
  fi
done
exit "$failed"

Save it as ~/terminal-practice/pagecheck/pagecheck with nano (mkdir -p ~/terminal-practice/pagecheck first), chmod +x it, and ask it about itself from that folder:

./pagecheck --version
./pagecheck --help

pagecheck 1.0.0
Usage: pagecheck [FOLDER]
Checks that every .html page in FOLDER has a <title>.
Leave FOLDER out to check the folder you're in.

  --help      show this help
  --version   show the version number

Exit code 0 when every page has a title, 1 when one doesn't.

1.0.0 is a semantic version, read "major, minor, patch". Fix a bug, and it becomes 1.0.1. Add an option, 1.1.0. Change how people use it, so their own scripts would break, 2.0.0. The number tells people whether it's safe to update.

A README and a license

A README is the first file people read: what the tool does, how to install it, and one example. On GitHub it shows on the project's front page. README.md is written in Markdown, where # starts a heading:

# pagecheck

Checks that every web page in a folder has a <title>.

## Install

    git clone https://github.com/your-name/pagecheck.git
    cd pagecheck && ./install.sh

## Use

    pagecheck site

Prints each page that has no title, and ends with exit code 1 if it found one.

## License

MIT. See LICENSE.

A license says what others may do with your code. Without one, the law treats it as yours alone: people can read it, but they have no permission to copy, change or share it. Shared tools usually choose an open source license, which gives that permission. The MIT License, one of the most used, lets anyone use, copy and change the code as long as they keep your name and the license text with it. The GNU GPL also asks that changed versions they share stay under the GPL. GitHub's site choosealicense.com compares them in plain words. The license goes in a file named LICENSE, beside the README.

An install script

install.sh does what Run It from Anywhere: ~/bin on Your PATH did by hand, and then checks the result with command -v:

#!/usr/bin/env bash
# install.sh: installs pagecheck in ~/bin, your own commands folder.
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"

mkdir -p ~/bin
cp pagecheck ~/bin/pagecheck
chmod +x ~/bin/pagecheck
echo "Installed $(~/bin/pagecheck --version) in ~/bin"

if ! command -v pagecheck > /dev/null; then
  echo "Your PATH doesn't include ~/bin yet. Add it, then open a new terminal."
fi

Save it beside pagecheck, make it runnable, run it, and try the new command from your home folder:

chmod +x install.sh
./install.sh
cd ~
pagecheck terminal-practice/bakery-site/site && echo "Every page has a title."

Installed pagecheck 1.0.0 in ~/bin
Every page has a title.

If ~/bin isn't on your PATH yet, the script says so instead of leaving you to wonder why pagecheck is "command not found".

Publishing it on GitHub

With those four files (pagecheck, install.sh, README.md and LICENSE), the tool is ready to share. The steps, when you have something to publish:

  1. On GitHub, click +, then New repository, name it pagecheck, and choose Public. GitHub can add an MIT LICENSE file for you from the same page.
  2. Send your folder to it with the same Git commands you use to submit an exercise.
  3. Mark the version, so people can download exactly 1.0.0, then turn the tag into a release under Releases on the project's page:
git tag v1.0.0
git push origin v1.0.0

Anyone can then install it with the two lines in your README.

Check yourself

2 questions to try on the lesson page.

So what

A script that answers --help, knows its version, installs itself and says what others may do with it stops being a file you send and becomes a tool people can find, trust and use.

Key terms

Cheat sheets

Related