Using git as a version controller for books (Part 1)

Posted On June 12, 2020

What’s git? Version control? Huh?

Okay. So, let’s say that you’re a software programmer. It’s your job to write the code for this huge program and you need:

• A way to keep backups
• A way to manage files
• A way to restore previous edits

Let’s say you’re collaborating with other software programmers, too. Now you need those things plus:

• A way to integrate changes to code made by other people
• A way to set aside different versions of the code, to test which version is optimal
• A way to mark which code to incorporate into the final product

All of these things are my simplified (non-software-engineer) explanation of version control. git, then, is a software program that helps you keep track of various file versions, throughout whatever changes you may introduce to them.

Git was originally written by Linus Torvalds, the creator of the Linux Kernel, as a way to track changes in the source code of the kernel. The Linux kernel is what is responsible for the interaction of the operating system and the hardware.

K, so it’s for programmy stuff, but you’re talking about books. So ???

Right. Well, I first have to say that this idea is not original. Some people I idolize use git to track their research papers. I became inspired to do this for the monograph I’m currently writing when I looked into the workflow of Language Science Press. They use a lot of open source programs, such as LaTeX, to typeset and publish their books, in a revolutionary form of “open access publishing”. One of the steps in that workflow is to use GitHub for version control.

GitHub is a website that hosts repositories created by git. Similarly to how Dropbox or Google Drive host repositories of your files, git hosts the various versions of files that you send to it. It’s more like Google Drive for very anal-retentive people, because keeping track of versions is very tedious.

Why do it?

When I wrote my master’s thesis, I had tons of Word Documents everywhere. Whenever I made a significant change, I had to save it with a new name, new date, new time… Something like that. If my advisor added annotations, I would save that, and then save another version where I went through and either accepted (and hardly ever rejected) her change suggestions. The number of files quickly added up.

So, what if, I thought, I could use git in a way that would reduce the number of visible files in my directory, but would allow for the multiple versions to still be present and restorable? Better yet, how could I use my webserver to store a copy of the repository, while also storing it on GitHub, for extra safe-keeping?

It turns out that git’s own website had the answers to those questions and more in the online version of Pro Git, by Scott Chacon. I’ll try to delineate what I had to do here:

Install git on a private server

Warning: I’m writing this tutorial to show how I did it on my Linux machine. I have no idea how this would be done on Mac or Windows. I likewise have no desire of finding out. Sorry. 🙁

The tutorial heavily borrows from THIS and THIS, but I improve on a few things that made the process simpler for me.

Because I first wanted to send my files to my own private server, away from Microsoft’s grip, I had to first log in to my server and install git there. As I run Ubuntu on my web server, the command was simple:

~$ sudo apt install git

That’s it. Git is now installed. We’re not done yet, though. We need to make a user just for git and assign it its own HOME directory (Linux has HOMES). That’s done with the command here:

~$ sudo useradd -m git

Now, we’ll add a password:

~$ sudo passwd git

It’s probably a good idea to add an SSH key to remotely login as your “git” user without a password. So, on your local machine, ensure that ssh is installed. If not, run:

~$ sudo apt install ssh

And then create a private ssh key by running the command (again, on your local computer, not the server):

~$ ssh-keygen -t rsa

That should create a key in your $HOME/.ssh directory. So, navigate there:

~$ cd ~/.ssh

And check to see if there is a file named “id_rsa.pub”. Assuming there is, you have to take that public key’s contents and put it on your remote server in the “git” user’s $HOME/.ssh/authorized_keys file. If you successfully do this, you should be able to login remotely as the “git” user:

~$ ssh git@server.ip.address

You should then be in the /home/git directory on your server. Run the pwd command to make sure and you should see “/home/git” as the output.

One place where I vary from the tutorials on the internet is the directory in which I choose to store my git projects on my server. As git doesn’t really care where you store your projects (as long as it can get access), I wanted to store them in the HOME directory of my “git” user account, rather than in the /srv/git directory, like many tutorials suggested. So, logged in as “git”, I ran this command:

~$ mkdir git-projects && cd git-projects

That string both created and took you into a git-projects directory. Now, you can start making git directories to make your project. Since this tutorial is about book versioning, let’s make a repository called “book.git”:

~/git-projects$ mkdir book.git && cd book.git

Now that we’re inside of it, we can create a bare git project with the git init command:

~/git-projects/book.git$ git init --bare
Initialized empty Git repository in /home/git/git-projects/book.git/

Let’s now choose a directory in our local computer to link to the blank git repository we’ve just made. I’ll find a folder, called “my_book” with some Word Docs in it and cd to it.

~$ cd Documents/my_book

I’ll now indicate that this folder is part of a git project, with the command (bold):

~$ git init
Initialized empty Git repository in /home/tyler/Documents/my_book/.git/

If there are already files in the folder, I can add them all to my git project with the simple command:

~$ git add .

I’ll now commit all of the files into the first commit by typing (bold):

~$ git commit -m "Initial commit"
[master (root-commit) 4d3d5cf] Initial commit
3 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 doc1.doc
create mode 100644 doc2.doc
create mode 100644 doc3.doc

Now my documents in the folder have been committed to the git project. So, how do I get them on my server? First, I have to specify my server as an origin with this command:

$ git remote add origin git@server.ip.address:/home/git/git-projects/book.git

Finally, we can “push” our project to that server:

$ git push origin master
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 227 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@server.ip.address:/home/git/git-projects/book.git
[new branch] master -> master

And that’s it! You’ve now backed up your files on a remote server using git! As this post has gone on long enough, I’ll tell you how I linked my directory to my private server and to GitHub at the same time. Thanks for reading!