I work on a lot of different coding projects. Websites, front end and back, Mac and iOS coding, Ruby gems, scripting, design projects. While I’m working on a project, the build, deploy, and other development processes I set up become second nature. Once I’ve moved to another project or 20, I’ve learned it’s really easy to forget how I had it all set up. Maybe I was using CodeKit, or maybe I had gulp-watch set up, maybe everything is in a Rakefile…
As a result, I take notes whenever I set up Grunt or Gulp, add npm tasks, build out a rakefile, or just create some shell scripts to automate my processes. Just a reminder of what the process is and what tricks I’ve been up to. The notes are saved in the root directory, and I add the notes to the project’s git repo; they can help me save time explaining things to any collaborators, but mostly they’re just there so that when I dig the project up a year later, I don’t have to dig through all of the config files to remember what’s what.
To that end, I wrote a simple script to find these build notes and show me all or any given section of them. It relies on there being a file in the current directory with a name that starts with “build” and an extension of “.md”, “.txt”, or “.markdown”. I usually call mine “buildnotes.md,” but it will find anything matching those criteria.
The sections of the notes are delineated by Markdown headings, level 2 or higher, with the heading being the title of the section. I split all of mine apart with h2s. For example, a short one from the little website I was working on yesterday:
The script isn’t terribly advanced. It expects there to only be one header level used to split sections. Anything before the first header is ignored.
Sometimes I write more detailed notes, but the above project was pretty straightforward. I did, however, end up with config files from multiple package managers around from my discovery phase, so until I clean it up you couldn’t just look at the directory and tell what package manager or build system to use. Ultimately, I just need enough info to know where to look for more details. If I know that I was compiling my css with gulp and compass, I know I’m looking for a gulpfile.js and a sass folder to start editing the CSS.
To use the tool, save the script to a file and make it executable (
chmod a+x buildhelp.rb). I alias the script to
build?, which makes it really easy to remember (I just ask the question, “build?”). To do so, just add
alias build?="/path/to/buildhelp.rb" to your
.bash_profile or wherever your aliases are stored.
Now with a build notes file in the directory I’m in, if I run
build? in the root folder, it will output a colorized version of that entire file. I can also get specific sections by including the section name (case insensitive, only the first few characters needed to match).
build? -s and it will list all of the sections in the file:
build? dep to get just the Deploy notes.
I know it’s a bit silly, but keeping a consistent system as I move through different projects helps keep me sane and avoid wasting time tracking down my tools. If it sounds helpful, grab the script from this gist.