At OSEDEA, we know one of the hardest things to do as software developers is documenting our code and keeping that documentation up-to-date is even more difficult.
The issue here is not that we don't want to document our code, we just don't think about it while we code.
This creates a situation in which we arrive at the end of a Sprint (or 2, or 3) and have done no documentation. And then, it hurts.
If it hurts, do it more often Martin Fowler
Even if this sentence usually applies to continuous integration, it is true as well for documentation. Introducing the task of documenting the code into our workflow is the solution we found at OSEDEA to tackle that problem.
Most of the time, it might add 5-10 minutes to document a new feature, but it is such a big win on the lifetime of a project that you will definitely win it back as soon as another developer has to onboard the project.
That's why, to simplify our everyday lives as developers, a member of the team created a tool to allow us to write documentation using the command-line, and that's where git comes into play.
Using git to structure your workflow
Git is amazing. Any developer who knows or learns about git
It is amazing for a lot of reasons, but today, I'm going to talk about automating some processes in your workflow.
Git offers a set of hooks that you can customize to modify your workflow.
Let's look specifically at the
First, take a repository that you would like to try out on and setup your hook.
$ cd my-awesome-repo/
Your hooks are stored in each repository in the
$ ls -la .git/hooks --- total 88 drwxr-xr-x 12 osedea staff 408 29 May 09:43 . drwxr-xr-x 16 osedea staff 544 29 May 09:44 .. -rwxr-xr-x 1 osedea staff 478 1 Jul 2016 applypatch-msg.sample -rwxr-xr-x 1 osedea staff 896 1 Jul 2016 commit-msg.sample -rwxr-xr-x 1 osedea staff 189 1 Jul 2016 post-update.sample -rwxr-xr-x 1 osedea staff 424 1 Jul 2016 pre-applypatch.sample -rwxr-xr-x 1 osedea staff 1642 1 Jul 2016 pre-commit.sample -rwxr-xr-x 1 osedea staff 1348 1 Jul 2016 pre-push.sample -rwxr-xr-x 1 osedea staff 4951 1 Jul 2016 pre-rebase.sample -rwxr-xr-x 1 osedea staff 1239 1 Jul 2016 prepare-commit-msg.sample -rwxr-xr-x 1 osedea staff 3610 1 Jul 2016 update.sample
Create a pre-commit file in
#!/bin/bash exec < /dev/tty # Allows the script to ask input of the User echo -e "\033[1;43mIs your Documentation up-to-date? (y/n)\033[1;0m" # The question the script will ask me, with a nice Yellow background color (see [this link](http://misc.flogisoft.com/bash/tip_colors_and_formatting) for more about that read answer if echo "$answer" | grep -iq "^y" ;then echo -e "\033[1;42mYou're so awesome!\033[1;0m" # Positive feedback and let the flow continue else echo -e "\033[1;41mBad you!\033[1;0m" # Negative feedback exit 1 # Exit fi
For your hook to be used by git, it needs to be executable, so be sure to
chmod +x it!
Now try it!
$ touch test-committing $ git add test-committing $ git commit -m "This is a test" --- Is your Documentation up-to-date? (y/n) n Bad you! --- $ git commit -m "This is a test" --- Is your Documentation up-to-date? (y/n) y You're so awesome! [dev 3422755] This is a test 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 test
To remove your commit, just
git reset HEAD~1 && rm test-committing
I am not going to talk about it today, but know that the
post-commit hook can be very useful as well, and works exactly the same way.
As of git 1.7.1, you can set init.templatedir in your gitconfig to tell git where to look for templates.
Set it like this:
git config --global init.templatedir '~/.git_template'Afterward, new repositories you create or clone will use this directory for templates. Place the hooks you want in ~/.git_template/hooks. Existing repositories can be reinitialized with the proper templates by running git init in the same directory .git is in.
For git versions older than 1.7.1, running git init --template ~/.git_template will work if you're like me and still want to manage your .git_template dir along with the rest of your dot files. You can also use the $GIT_TEMPLATE_DIR environment to tell git init where your template directory is. Thank you, Stackoverflow Users! (source)
Move your pre-commit script into your newly created
~/.git_template/hooks folder and test out if git is getting it:
$ # Still in the `my-awesome-repo/` folder $ mkdir -p ~/.git_template/hooks $ mv .git/hooks/pre-commit ~/.git_template/hooks $ git init $ cat .git/hooks/pre-commit
You should see your hook there, brought back by the
git init, and it should be there by default in any new or cloned repository thereafter!
Git hooks are very powerful and I think they can be used to make everyone in the team more efficient.
You can do whatever you want in them, including, running your tests, your linter, etc.
Finally, if you need to push a really important fix in production right now and don't have the time to worry about documentation or linting, do not worry, you can always skips the hooks with
git commit --no-verify.
I hope you liked this article, feel free to share it, comment below to give us feedback or kuddos. :)