3 ms·
We use this at my place, though in bash, and we call it executable documentation. Stuff like: NAME="$1" # Create directory for the code mkdir "$NAME" # Chec
by dusted 7y ago
We use this at my place, though in bash, and we call it executable documentation.
Stuff like:
NAME="$1"
# Create directory for the code
mkdir "$NAME"
# Checkout the source
cd $NAME && git something
# and so on
Sometimes with an
echo "You need to read and understand this before just using it"; exit 1 thrown in somewhere for good measure.
These files will have no logic, and make very little use of variables. They will also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which just so happens to be a valid bash script.
- dharmab 7y agoWe embed similar explanatory docs in Markdown. A short example for dig from our troubleshooting guide: # General form dig @<resolver> <record> dig @1.1.1.1 www.example.com # Omit the resolver to use the system's configured resolvers dig www.example.com # Don't need the full output? dig +short www.example.com
- meowface 7y agoThis sounds like basically what I use READMEs or supplementary Markdown documentation files for, just in a bash code block in a Markdown file rather than in a bash file.
- peterbell_nyc 7y agoThe difference is that every time you do the process, you can consider writing a couple of tests and automating the step.
- meowface 7y agoThat's true. I guess I tend to just use those as examples/documentation at the start, and then when I want to automate the process, I do it more in an all-at-once way (with a Python project or something) rather than incremental additions to a bash script. Do-nothing scripting does definitely sound like a technique I should try out. I'm not a huge fan of bash for stuff beyond a list of short commands/steps, though.
- qznc 7y agoYou could prefix the script with `#!/bin/bash -vn` and make it executable. It will just print itself.
- thunderbong 7y agoThanks. Didn't know about this.