- December 15, 2016
The "Cog" File
- @mrpaulphan
- Development Co-Op
On any given week, I might be working on 2-3 different projects at a time.
I’ll often have to dip into an old project, start a new project, or assist another developer in their current project. When you’re dealing with so many files with so many different authors, you realize the importance of a well documented and updated README file. Every project has its own requirements, installation processes, coding styles, content management system, etc. A well documented README file can save a developer hours of time.
A few weeks ago, I ran into a situation where I had to pull in another a developer to help me finish up some work before an upcoming milestone. I directed her to our repository and she had the project up and running in a few minutes. I was excited by how quickly and easily she was able to get the project started, thanks to our internal documentation. I’ve lived through three hour `npm install` debugging sessions before where versions aren’t documented or dependency conflicts arise. This validated the importance of documenting every project setup. Saving time here allowed me to focus on my current work instead of wasting both of our time trying to spin up the project locally on her machine.
Happy Cog alum Dan Delauro, who wrote articles such as “Deploying Static Websites to AWS S3 Behind an Nginx Proxy” and “Gone zshin”, implemented what we affectionately call the “Cog” file. This file is a bash script that masks away all the heavy lifting in each project. Each cog file is custom to each project.
The Cog Commands
In terminal, Running `cog` will print a list of available commands we have available for this django app.
These commands can vary from project to project.
Whether the project is built with Django, Laravel, CraftCMS, Patternlab, or any other framework/cms, running `cog setup` will initially configure the entire project. This will install all the required packages, setup the local db, configuring your .env file, etc.
As of now, to automate our task we use either gulp or grunt. Sometime in the future we could be using who knows what. We can mask the default preprocessor by running `cog dev`.
The `cog go` command might be my favorite because with it we can start a docker container, run the built in PHP web server, or just about type of web server.
Invest the time
Not limited to the examples listed above, the cog file is a very powerful script. Instead of having lines of code to copy and paste to do all of these tasks, we compile it into one cohesive script. The time we invest into our documentation and cog files certainly benefits us as a team and saves us countless hours in the future. Do you have a different approach? How do you automate your workflow? Is your README file well-documented? I’d love to hear from you.