Setting up a writing project on GitLab

As I've mentioned on my blog before, I write novels using Markdown. I also keep everything in a Git repository which helps prevent me from overwriting chapters or giving me a chance to commit changes while at the family cabin.

The biggest advantage of Git is the ability to coordinate writing between two computers (laptop and basement). This requires a third computer, a remote repository, to handle working between the two machines. Until a few months ago, I used a SSH host to handle them.

Then I found out that GitLab had much of the features of my favorite (and just about everyone else) host, GitHub. The main difference is GitLab is open-sourced and less popular while GitHub a private company, closed-source, but very popular.

I really like GitHub, mainly because of their interface. But they don't allow for private repositories. And I like to keep my novels private until they are released under Creative Commons.

Fortunately, GitLab allows for unlimited private repositories. Also, they have a omnibus edition which lets someone like me (somewhat technical) host their own private version outside of a third-party's server. That isn't important for many people, the GitLab hosted version is probably good for many writers.

Setting up a project

You can click on the images for larger versions.

GitLab Setup

Setting up projects is pretty easy. Create an account over at GitLab and select “New Repository”. This will ask some basic information, the only thing I enter is a slug, a name with dashes, that identifies the project. For example, my novel Sand and Ash would have a slug of “sand-and-ash”.

Also make sure the project remains as “Private” which means only people you explicitly give access to the project can do so.

GitLab example #1

Once you set up a project, this brings you to the dashboard. This is where you can list all the files in the project, or view the check-ins. You can also use “merge requests,” which I haven't had a chance to investigate. In theory, you could have an editor work on sections and then push out those changes for you to review.

The other aspects of use are milestones and issues. I use both of these pretty frequently to keep track of things to do before publication (or updates if you happen to need an update).


GitLab example #2

GitLab example #3

Milestones are significant points in the novel's life. I use Semantic Versioning to identify the versions of the novel with 1.0.0 being the first release. Before that, I start with a number of them that represent the first three rounds of edits (0.1.0, 0.2.0, and 0.3.0), the one-off rounds (say clean up quotations or look for echo words), alpha readers (0.4.0), editor rounds (0.5.0 through 0.8.0), and final beta reading (0.9.0 and higher).

Setting up a milestone is pretty easy. Click on the “Milestones” lists all the milestones and then click on “New Milestone”. From there, you can enter a milestone, you give it a name (“v1.0.0” for the initial release) and a short description. I'd love to have a due date, but I can't publish reliably enough for that so I don't pick one. That way, it won't nag me about failing to meet my self-imposed deadline.


GitLab example #4

GitLab example #5

GitLab example #6

GitLab example #7

GitLab example #8

GitLab example #7

Issues are done the same way as Milestones, but an issue can have a milestone associated with it which is why I do those first. It may not make sense to do issues, but I find them very helpful with the little things that always get lost. The easy issues are “get editing done” and “create a cover”, those can be assigned to a milestone without a problem.

In other times, while I'm working on the story, I'll realize that I need to go through the entire document and fix one specific item. When I realize these things, I'm either in the process of writing something else or I can't focus on it. For these situations, I'll create an issue to go through the book later and then I don't have to worry about forgetting it.

Some examples:

  • Make sure Rutejìmo has his weapon from chapter 18 on
  • Create the epigraphs at the beginning of the chapters
  • Enter the epigraphs into the wiki site
  • Correct a character's name because it was confusing with another one
  • Back-fill foreshadowing for something
  • Add details about a city.

One really nice feature of GitLab is that one issue can reference another one. If you type an octothorpe ("#"), the system will present a drop-down list of existing issues. There is some search by typing to reduce the list. This comes in handy if you have an issue that depends on another one (updating the wiki requires details being written).

While entering issues, you can use Markdown to create links, bold, italic, and even include images. Most of it is pretty easy if you use the editor bar (images are drag-and-drop).

When I create issues, many times I assign them to a milestone if I know it. For example, “updating the wiki site” is a v1.0.0 milestone. I noticed that the earlier releases will get 10-20 issues assigned to them but the later ones get more precise. They also focus on different things. “Assign ISBN” is a much later task compared to “Make sure he has green eyes.”

One nice thing about tracking tasks and items like this is that I get a list of things that I've done and ones that I have left to do. I found that some evidence of forward momentum helps in those moments when I'm most discouraged about writing ("I'm never going to finish…").

This a technical way of managing books and writing. For me, this works out pretty well because I use the same tools for programming. I'm also easily distracted (e.g., have too many projects), so being able to track the little things that go into writing something like a novel.