Keeping track of all your projects’ build systems

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:

## Build

gulp js: compiles and minifies all js to dist/js/main.min.js

gulp css: compass compile to dist/css/

gulp watch

gulp (default): [css,js]

## Deploy

gulp sync: rsync /dist/ to scoffb.local

## Package management

yarn

## Components

- UIKit

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).

Run build? -s and it will list all of the sections in the file:

- Build
- Deploy
- Package management
- Components

Then run 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.

Brett Terpstra

Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on Twitter, GitHub, and Mastodon. Keep up with this blog by subscribing in your favorite news reader.

This content is supported by readers like you.

Join the conversation