John Bokma's Hacking & Hiking

Keeping your blog under version control with git

Because tumblelog works with a single input file there is a risk of typing in the wrong place and modifying an old blog entry by accident and overlook this change. With version control such accidents are easy to spot and correct.

Getting started with git

Change the current working directory to your websites local directory and enter:

git init

This should report a line similar to the one given below:

Initialized empty Git repository in /home/john/sites/example.com/.git/

If you type ls -a1 in your site's working directory you get a result similar to the one given below:

.
..
example.html
example.md
.git
htdocs
Makefile
.sass-cache

The files I recommend to keep under version control are the Markdown file, the Makefile, and the template file.

But first let's tell git to ignore the .sass-cache and htdocs directories; don't use git as a backup program.

Create an empty file called .gitignore and add the following two lines to it:

.sass-cache
htdocs

Depending on the contents of your working directory you might want to add more entries to this. For example .DS_Store if you're on macOS.

Now, if you type git status you should get a report similar to the one given below:

On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	.gitignore
	Makefile
	example.html
	example.md

nothing added to commit but untracked files present (use "git add" to track)

If you notice any entries in this list that you don't want under version control add those entries to .gitignore first.

Intermezzo: tell git who you are

Before you can commit, you have to tell git who you are. The program keeps track of changes made to file(s) and attributes those changes to someone.

Run the following two commands:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

With git config --list you can verify those settings.

The above two commands have to be done only once as they are stored inside a global configuration file.

The first commit

If all went well git status should only show the files you want under version control. Next, type

git add .

to add the files listed to the so-called staging area. Now we are ready to do our first commit:

git commit -m 'Initial commit'

A file has changed: the second commit

Now, when you make a change to, for example, the Makefile you can see what exactly has changed using the git diff command. For example, I changed the stylesheet from Steel to Happy Cat:

diff --git a/Makefile b/Makefile
index 5ae6fcb..7c75a09 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,8 @@
 TUMBLELOG = ../../tumblelog
 PYTHON = python3
-SCSS = steel.scss
+SCSS = happy-cat.scss
 SASS = sass --sourcemap=none -t compressed
-CSS  = steel.css
+CSS  = happy-cat.css
 DOMAIN = example.com
 TEMPLATE = example.html
 AUTHOR = 'John Bokma'

A line with a - in front means that this line has been deleted and a line with a + in front has been added.

If this is an accident, or you want to revert this change, you can use git checkout -- Makefile to get the old version back. But let's assume this is a desired change, so we add this file to the staging area using:

git add Makefile

Check with git status that the file has been added to the staging area. Note that we can undo this step with git reset HEAD Makefile.

Now we can commit this change. The recommended way to write a commit message is to write it as a instruction to yourself explaining what to do to get at the new version. For example, in this case:

git commit -m 'Change style from Steel to Happy Cat'

Keep the message short and to the point. For more information on writing commit messages, see How to Write a Git Commit Message.

With the command git log you can read back your commit messages, for example:

commit d89a710d14a9970e0a8a49a639b924d996a0f0dd (HEAD -> master)
Author: John Bokma <contact@johnbokma.com>
Date:   Wed Oct 16 23:17:04 2019 +0200

    Change style from Steel to Happy Cat

commit fde3d4277c1d1ee0bd28b429de39333a3e31a4d1
Author: John Bokma <contact@johnbokma.com>
Date:   Wed Oct 16 20:15:43 2019 +0200

    Initial commit

You can add the --oneline option to get one line per entry:

d89a710 (HEAD -> master) Change style from Steel to Happy Cat
fde3d42 Initial commit

Committing the blog

I commit my blog, the Markdown file every Sunday, which is the end of a week in tumblelog. I use Update blog to week n with n the week number as commit message. Before I commit the blog, I always check with git diff if I didn't accidentally modified older entries.

You can also decide to commit the blog daily, it's up to you.