# Git and writers
by Seth Kenlon
Some people write fiction, others write academic papers, others poetry,
screenplays, technical manuals, or articles about open source. Many do a
little of each. The common thread is that if you're a writer, you could
probably benefit from using Git. While Git is famously a highly
technical tool used by computer programmers, it's actually ideal for the
modern author, and this article will demonstrate how it can change the
way you write and why you'd want it to.
Before talking about Git, though, it's important to talk about what
*copy* (or *content*, for the digital age) really is, and why it's
different from your delivery medium. It's the 21st century, and the tool
of choice for most writers is a computer. While computers are
deceptively good at combining processes like copy editing and layout,
writers are [re]discovering that separating content from style is a
really good idea, after all. That means you should be writing on a
computer like it's a typewriter, not a word processor. In computer
lingo, that means writing in *plain text*.
Writing in plain text
=====================
It used to be a safe assumption that you knew what market you were
writing for. You wrote content for a book, or you wrote content for a
website, or for a software manual. These days, though, the market's
flattened: you might decide to use content you write for a website in a
printed book project, and the printed book might release an EPUB version
later. And in the case of digital editions of your content, the person
reading your content is in ultimate control: they may read your words on
the website you published on, or they might click on Firefox's excellent
[Reader
View](
https://support.mozilla.org/en-US/kb/firefox-reader-view-clutter-free-web-pages),
or they might print it to physical paper, or dump the web page to a text
file with `lynx`, or they may not see your content at all because they
use a screen reader.
It makes sense to write your words as words, leaving the delivery to the
publishers. Even if you are also your own publisher, treating your words
as a kind of source code for your writing is a smarter and more
efficient way to work, because when it comes time to publish you can use
the same source (your plain text) to generate output appropriate to your
target (PDF for print, EPUB for ebooks, HTML for websites, and so on).
Writing in plain text not only means that you don't have to worry about
layout or how your text is styled, but that you no longer require
specialized tools. Anything that can produce text becomes a valid "word
processor" for you, whether it's a basic notepad app on your mobile or
tablet, or the text editor that came bundled with your computer, or a
free editor you download from the Internet. You can write on practically
any device, no matter where you are or what you're doing, and the text
you produce integrates perfectly with your project, no modification
required.
And conveniently, Git specializes in managing plain text.
The Atom editor
===============
When you write in plain text, a word processor is overkill. Using a text
editor is easier, because text editors don't try to "helpfully"
restructure you input. It lets you type the words in your head onto the
screen, no interference. Better still, text editors are often designed
around a plug-in architecture such that the application itself is
woefully basic (it edits text) but you can build an environment around
it to meet your every need.
A great example of this design philosophy is the [Atom](
http://atom.io)
editor. It's a cross-platform text editor with built-in Git integration.
If you're new to working in plain text and new to Git, then Atom is the
easiest way to get started.
Installation
============
First, make sure you have Git installed on your system. If you run Linux
or BSD, Git is available in your software repository or ports tree. The
command you use will vary depending on your distribution; on Fedora, for
instance:
$ sudo dnf install git
If you're on Mac, download and install Git from
[git-scm.com/download/mac](
https://git-scm.com/download/mac).
If you're on Windows, download and install Git from
[git-scm.com/download/win](
https://git-scm.com/download/win).
You won't need to use Git directly because Atom serves as your Git
interface. Installing Atom is the next step.
If you're on Linux, install Atom from your software repository through
your Software Installer or the appropriate command, such as:
$ sudo dnf install atom
If you're using BSD, Atom does not currently build on your platform.
However, there are very good alternatives available, such as [GNU
Emacs](
http://gnu.org/software/emacs).
For Mac and Windows users, there are installers for Atom on
[atom.io](
http://atom.io).
Once all of your installs are done, launch the Atom editor.
A quick tour
============
If you're going to live in plain text and Git, you need to get
comfortable with your editor. Atom's user interface is possibly more
dynamic than what you may be used to. You can think of it more like
Firefox or Chrome than as a word processor, in fact, because it has tabs
and panels that can be opened and closed as they are needed, and it even
has add-ons that you can install and configure. It's not practical to
try to cover all of the many features of Atom, but you can at least get
familiar with what's possible.
When Atom opens, it displays a welcome screen. If nothing else, this
screen is a good introduction to Atom's tabbed interface: close the
welcome screens by clicking the close icons on the tabs at the top of
the Atom window. Create a new file in the FileNew File.
Working in plain text is a little different than working in a word
processor, so here are some tips for how to write content in a way that
you as a human can connect with, but that Git and computers can parse,
track, and convert.
Write in Markdown
-----------------
These days, when people talk about plain text, mostly they mean
Markdown. Markdown is more of a style than a format, meaning that its
intent is to provide a predictable structure to your text so that
computers can detect natural patterns and convert the text
intelligently. Markdown has many definitions, but the best technical
definition and cheatsheet is
[commonmark.org](
https://commonmark.org/help/).
# Chapter 1
This is a paragraph with an *italic* word and a **bold** word in it.
And it can even reference an image.
As you can tell from the example, Markdown isn't meant to read or feel
like code, but it can be treated like code. If you follow the
expectations of Markdown, as defined by the
[commonmark.org](
https://commonmark.org/help/) definition, then you can
reliably convert, with just one click of a button, your writing from
Markdown to a `.docx`, `.epub`, `.html`, `mediawiki`, `.odt`, PDF,
`.rtf`, and a dozen other formats *without* loss of formatting.
You can think of Markdown a little like word processor Styles. If you've
ever written for a publisher with a set of styles that govern what
chapter titles and section headings look like, this is basically the
same thing except that instead of selecting a style from a drop-down
menu, you're adding little notations to your text. These notations look
natural to any modern reader who's used to "txt speak", but get swapped
out with fancy text stylings when the text is rendered. It is, in fact,
exactly what word processors are doing secretly behind the scenes when
you use them. The word processor shows you bold text, but if you could
see the code being generated to make your text bold, it would be a lot
like Markdown (actually it's the far more complex XML). With Markdown,
that barrier is removed, which looks scarier on one hand, but on the
other hand you can write Markdown on literally anything that generates
text without losing any formatting information.
The popular file extension for Markdown files is `.md`. If you're on a
platform that doesn't know what a `.md` file is, you can associate them
to Atom manually, or else just use the universal `.txt` extension. The
file extension doesn't change the nature of the file, it just changes
how your computer decides what to do with it. Atom and some platforms
are smart enough to know that a file is plain text no matter what
extension you give it.
Live preview
------------
Atom features the Markdown Preview plugin, which shows you both the
plain Markdown you're writing and the way it will [commonly] render.
To activate this preview pane, select the Packages Markdown Preview
Toggle Preview or press CtrlShiftM.
This view provides you with the best of both worlds. You get to write
without the burden of styling your text, but you also get to see a
common example of what your text will look like, at least in a typical
digital format. Of course, the point is that you can't ultimately
control how your text is rendered, so don't be tempted to adjust your
Markdown to force your render preview to look a certain way.
One sentence per line
---------------------
Your high school writing teacher doesn't ever have to see your Markdown.
It won't come naturally at first, but maintaining one sentence per line
really does make more sense in the digital world. Markdown ignores
single line breaks (when you've pressed the Return or Enter key), and
only creates a new paragraph after a single blank line.
The advantage to writing one sentence per line is that your work is
easier to track. That is, if you've changed one word at the start of a
paragraph, then it's easy for Atom and Git, and in fact any application,
to highlight that change in a meaningful way if the change is limited to
one line rather than one word in a long paragraph. In other words, a
change to one sentence should only affect that sentence, not the whole
paragraph.
You might be thinking that many word processors track changes, too, and
they can highlight a single word that's changed. But those revision
trackers are bound to the interface of that word processor, which means
you can't look through revisions without being in front of that word
processor. In a plain text workflow, you can review revisions in plain
text, which means you can make or approve edits no matter what you have
on hand, as long as that device can deal with plain text (and most of
them can).
Writers admittedly don't usually think in terms of line numbers, but
it's a useful tool for computers, and ultimately a great reference point
in general. Atom numbers the lines of your text document by default. A
*line* is only a line once you have pressed the Enter or Return key.
If a line has a dot instead of a number, that means that it's actually
part of the previous line wrapped around for you because it couldn't
physically fit on your screen.
Theme it
--------
If you're a "visual person", you might be very particular about the way
your writing environment looks. Even if you are writing in plain
Markdown, it doesn't mean you have to write in a programmer's font, or
in a dark window that makes you look like a coder. Atom can be themed
with theme packages.
The simplest way to modify what Atom looks like is to use [theme
packages](
https://atom.io/themes). It's conventional for theme designers
to differentiate dark themes from light themes, so you can search with
the keyword `dark` or `light`, depending on which you're looking for.
To install a theme once you've found one that you like, select
EditPreferences. This opens a new tab in the Atom interface. Yes, tabs
are used for both your working documents as well as for configuration
and control panels. In the Settings tab, click on the Install category.
In the Install panel, search for the name of the theme you want to
install. Click the Themes button on the right of the search field to
search only for themes. When your theme has been found, click its
Install button.
To use a theme that you've installed, or to customize a theme to your
own preference, navigate to the Themes category in your Settings tab.
Pick the theme you want to use from the drop-down menus. The changes
take place immediately, so you can see exactly how the theme affects
your environment.
You can also change your working font in the Editor category of the
Settings tab. Atom defaults to monospace fonts, generally preferred by
programmers. But you can use any font on your system, whether it's serif
or sans or gothic or cursive. Whatever you want to spend your day
staring at, it's entirely up to you.
On a related note, Atom by default draws a vertical marker down its
screen as a guide for people writing code. Programmers often don't want
to write long lines of code, so this vertical line is a reminder to them
to simplify things. The vertical line is meaningless to writers, though,
and you can remove it by disabling the `wrap-guide` package.
To disable the `wrap-guide` package, select the Packages category in the
Settings tab and search for `wrap-guide`. When you've found the package,
click its Disable button.
Dynamic structure
-----------------
It's not a requirement, but I find that writing one chapter per file
makes more sense than writing an entire book into a single file.
Furthermore, I don't name my chapters in the obvious syntax
`chapter-1.md` or `1.example.md`, but by chapter titles or key words,
such as `example.md`. To provide myself guidance in the future as to how
the book is meant to be assembled, I maintain a file called `toc.md`
(for "Table of Contents"), in which I list the [current] order of my
chapters.
The reason I do this is because, no matter how convinced I am that
chapter 6 just couldn't possibly happen before chapter 1, there's rarely
a time that by the end of a book, I haven't swapped the order of one or
two chapters or sections. I find that keeping it dynamic from the start
helps me avoid rename confusion, and also helps me treat the material
less rigidly.
Git in Atom
===========
Something every writer has in common is that they're writing for keeps,
and their writing is a journey. You don't sit down to write and finish
with a final draft but, by definition, a first draft. And that draft
goes through revisions, each of which you carefully save in duplicate
and triplicate just in case one of your files turns up corrupted.
Eventually, you get to what you call a final draft, but more than likely
you'll be going back to it one day, either to resurrect the good parts
or to fix the bad.
The most exciting feature in Atom is its strong Git integration. Without
ever leaving Atom, you can interact with all of the major features of
Git, tracking and updating your project, rolling back changes that you
don't like, integrating changes from a collaborator, and more. The best
way to learn it is to step through it, so here's how to use Git from
within the Atom interface from the beginning to the end of a writing
project.
First thing's first: reveal the Git panel by selecting ViewToggle Git
Tab. This causes a new tab to open on the right side of Atom's
interface. There's not much to see yet, so just keep it open for now.
Starting a Git project
----------------------
You can think of Git as being bound to a folder. Any folder outside a
Git directory doesn't know about Git, and Git doesn't know about them.
Folders and files within a Git directory are ignored until you grant Git
permission to keep track of them.
You can create a Git project by creating a new project folder to Atom.
Select FileAdd Project Folder and create a new folder on your system.
Once you've done that, the folder you've just created appears in the
left Project panel of your Atom window.
Git add
-------
Right-click on your new project folder and select New File to create a
new file in your project folder. If you have existing files you want to
import into your new project, right-click on the folder and select Show
in File Manager to open the folder in your system file viewer (Dolphin
or Nautilus on Linux, Finder on Mac, Explorer on Windows), and then drag
and drop your files.
With a project file (either the empty one you created or an existing one
you've imported) open in Atom, click the Create repository button in the
Git tab. In the pop-up dialog box that appears, click Init to initialize
your project directory as a local Git repository. Git adds a `.git`
directory (invisible in your system's file manager, but visible to you
in Atom) to your project folder. Don't be fooled by this: the `.git`
directory is for Git to manage, not you, so you'll generally stay out of
it. But seeing it in Atom is a good reminder that you're working in a
project actively managed by Git; in other words, revision history is
available when you see a `.git` directory.
In your empty file, write some stuff. You're a writer, so type some
words. It can be any set of words you please, but remember my writing
tips.
Press CtrlS to save your file. Once the file has been saved, it appears
in the Unstaged Changes section of the Git tab. That means the file
exists in your project folder but has not yet been committed over to
Git's purview. Allow Git to keep track of your file by clicking on the
Stage All button in the top right of the Git tab. If you've used a word
processor with revision history, you can think of this step as
permitting Git to record changes.
Git commit
----------
Your file is now staged. All that means is that Git is aware that the
file exists, and is aware that it has been changed since the last time
Git was made aware of it.
A Git `commit` sends your file into Git's internal and eternal archives.
If you're used to word processors, this is similar to formally naming a
revision. To create a commit, enter some descriptive text into the
Commit message box at the bottom of the Git tab. You can be vague or
cheeky, but it's more useful if you enter useful information for your
future self so that you know why the revision was made.
The first time you make a commit, you must create a branch. Git branches
are a little like alternate realities, allowing you to switch from one
time line to another to make changes that you may or may not want to
keep forever. If you end up liking the changes, then you merge one
experimental branch into another, thereby unifying different versions of
your project. It's an advanced process that's not worth learning up
front, but you still need an active branch, so you have to create one
for your first commit.
Click on the branch icon at the very bottom of the Git tab to create a
new branch.
It's customary to name your first branch `master`. You don't have to;
you cane name it `firstdraft` or whatever you like, but adhering to the
local customs can sometimes make talking about Git (and looking up
answers to questions) a little easier, because you'll know that when
someone mentions `master`, they really mean `master` and not
`firstdraft` or whatever you called your branch.
On some versions of Atom, the UI may not update to reflect that you've
created a new branch. Don't worry, the branch will be created (and the
UI updated) once you make your commit. Press the commit button, whether
it reads Create detached commit or Commit to master.
Once you've made a commit, the state of your file is preserved forever
in Git's memory.
History and Git diff
--------------------
A natural question is how often you should make a commit. There's no one
right answer to that. Saving a file with CtrlS and committing to Git are
definitely two separate processes, so you will continue to do both.
You'll probably want to make commits whenever you feel like you've done
something significant or are about to try out a crazy new idea that you
may want to back out of.
To get a feel for what impact a commit has on your workflow, remove some
text from your test document and add some text to the top and bottom.
Make another commit. Do this a few times until you have a small history
at the bottom of your Git tab, and then click on a commit to view it in
Atom.
When viewing a past commit, you see three elements:
1. Text in green got added to a document when the commit was made.
2. Text in red got removed from the document when the commit was made.
3. All other text was untouched.
Remote backup
-------------
One of the advantages of using Git is that it is, by design,
distributed, meaning that you can commit your work to your local
repository and then push your changes out to any number of servers for
backup. You can also pull changes in from those servers so that whatever
device you happen to be working on always has the latest changes.
For that to work, you must have an account on a Git server. There are
several free hosting services out there, including Github, the company
that produces Atom itself but oddly not open source itself, and one that
is open source, Gitlab. Preferring open source to proprietary, I'll use
Gitlab in this example.
If you don't already have a Gitlab account, sign up for one, and then
start a new project. The project name doesn't have to match your project
folder in Atom, but it probably makes sense if it does. You can leave
your project as Private, in which case only you and anyone you give
explicit permissions to, are able to access it, or you can make it
public if you want it to be available to anyone on the Internet who
stumbles upon it.
Do not add a README to the project.
Once the project is created, it provides you with instructions on how to
set up the repository. This is great information if you decide to use
Git in a terminal or with a separate GUI, but Atom's workflow is
different.
Click the Clone button in the top right of the Gitlab interface. This
reveals the address you must use to access the Git repository. Copy the
`SSH` address (not the `https` address).
In Atom, click on your project's `.git` directory and open the `config`.
Add these configuration lines to the file, adjusting the
`seth/example.git` part of the `url` value to match your unique address.
[remote "origin"]
url =
[email protected]:seth/example.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
At the bottom of the Git tab, a new button has appeared, labelled Fetch.
Since your server is brand new and therefore has no data for you to
fetch, right-click on the button and select Push.
This pushes your changes to your Gitlab account, and now your project is
backed up on a Git server.
Pushing changes to a server is something you can do after each commit.
It's immediate offsite backup, and usually the amounts of data being
sent is minimal, so it's practically as fast as a local save.
Writing and Git
===============
Git is a complex system, useful for more than just revision tracking and
backups. It enables asynchronous collaboration, it encourages
experimentation. This article has only covered the basics, but there are
many more articles, and in fact entire books, on Git and how to use it
to make your work more efficient, more resilient, and more dynamic. It
all starts with using Git for small tasks. The more you use it, the more
questions you'll find yourself asking, and eventually the more tricks
you'll learn.
