# 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 November 10, 2026 ## 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: ```bash #!/usr/bin/env bash # pagecheck: checks that every web page in a folder has a . 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: ```bash ./pagecheck --version ./pagecheck --help ``` ```text 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: ```text # 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`: ```bash #!/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: ```bash chmod +x install.sh ./install.sh cd ~ pagecheck terminal-practice/bakery-site/site && echo "Every page has a title." ``` ```text 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: ```bash 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 - [README](https://www.ask-codey.com/glossary/readme) - [Install Script](https://www.ask-codey.com/glossary/install-script) - [Semantic Versioning](https://www.ask-codey.com/glossary/semantic-versioning) - [Software License](https://www.ask-codey.com/glossary/software-license) - [Open Source](https://www.ask-codey.com/glossary/open-source) ## Cheat sheets - [Sharing Your Tool](https://www.ask-codey.com/cheat-sheets/bash-sharing-your-tool-cheat-sheet) ## Related - [Options and Flags: getopts and --help](https://www.ask-codey.com/lessons/bash-options-with-getopts) - [Run It from Anywhere: ~/bin on Your PATH](https://www.ask-codey.com/lessons/bash-scripts-on-your-path) - [The Scripts Every Project Has](https://www.ask-codey.com/lessons/bash-project-scripts) - [When to Reach for Another Language](https://www.ask-codey.com/lessons/bash-when-to-use-another-language) Source: https://www.ask-codey.com/lessons/bash-sharing-your-tool