What every git repository needs

Whenever I have an idea that is so brilliant that it actually warrants the creation of a brand new git repository, I usually end up with the files below.

$ tree -aI .git
.
├── .env
├── .env.example
├── .gitignore
├── LICENSE
├── Makefile
└── README.md

1 directory, 6 files

If you are not familiar with the above I’ll explain what these files are and why I create them.

setup environment variables with .env

Most projects that you create will need to use environment variables. Environment variables are nothing more then key value pairs like HOSTNAME=”apple.com”. The reason that we use environment variables is because it allows us to refer to these environment variables from within our code. This allows us to write code without hard coding values, which in turn makes our code portable. Portable code refers to software (or sections of software) that can be used, compiled, or executed on multiple computing platforms or environments with minimal to no modifications. Let me give you an example.

import os

hostname = os.getenv("HOSTNAME")
print(hostname) # outputs "apple.com"

You might question why go through all this trouble. Why not just put the value in the code, you say? Well, if you want to share the code with someone else, and that person needs to use a different value, they now need to change the code to make it work with their setup. Let’s say they need to use google.com instead. If you hard code the value, you have to change the value back to what it was. In this trivial illustration, you might not care. But as the code base gets larger, you will need to change a lot of values all over the place. Do you really want to go back and forth every time someone adds new code? If you are not convinced, think about what happens if your code needs to use a password. Do you really want to put that in your code for the world to see?

Note: Install direnv to export your environment variables automatically. Create the file $HOME/.config/direnv/direnv.toml with the below content.

[global]
load_dotenv = true

document environment variables with .env.example

We use the .env.example so developers can easily see which environment variables are necessary. You can now just copy that file to .env and immediately see which environment variables your code expects and just update the values.

do not accidentally commit secret values to your repository with .gitignore

Git ignores all files that are present in .gitignore. This is just a file which contains a list of names of files you absolutely do not want to have in your repository. Imagine what happens if you commit your .env file to the repository. You aren’t the first person to have leaked their secrets to Github!

protect yourself and others from legal ramifications with LICENSE

Writing code is easy, writing bug-free code is hard. Imagine that you have have written a bug in your code that deletes a database. And your code gets executed by someone working at a mega corporation. I believe most companies would take responsibility for their negligence, but what if they don’t? Are you prepared for the legal battle?

automate common actions with Makefile

Most projects include commands to bootstrap the project into their README.md. They mean well but that means that they now have to keep those commands up to date as the project grows and changes. Which they do not always remember to do. It also requires me to copy and paste the command from the readme into my shell. Instead, just put the command that you frequently use in the Makefile. This basically gives us executable documentation.

document your project with README.md

Here is where you document your project. Here you tell the users to copy the .env.example, which make commands to execute, and what the project does.

final thoughts

There you have it. This is the bare minimum of what I think a project should contain. Before you think or say, whaddabout X, Y or Z? Sure, by all means. This list is non-exhaustive and your approach might differ depending on what programming language you are using and what you are trying to do. Coming to think of it, I might extend this with Dockerfile. Maybe next time :)

references

• https://en.wikipedia.org/wiki/Environment_variable