Chapter 1 Introduction
Git, henceforth git, is a revision control system. What’s that? It is a tool to record changes to software, a tool to experiment with changes to software, and a tool to collaborate creating software. Why might an author want to use a tool designed to keep track of software? Presumably your writing is in an electronic form, and you may want to keep track of your work, you may want to experiment with different approaches to your writing, and you may collaborate with others, not least perhaps a copyeditor and an editor.
git has a powerful feature, know as branching, which allows you to branch off in two different directions with your writing. You can decide to tie the two branches back together later, with a process known as a merge or you can decide to keep one branch, and kill off the other. On a collaborative project, two different collaborators can work on two unrelated personal branches of the same project. These branches can be local to their own computers, with neither collaborator aware of, or concerned about, the other’s work. If their work is independent, then both collaborator’s additions may be merged into the project separately, or if their work overlaps, git can be used to resolve the overlaps.
Example 1.0.1. Heroine versus Hero.
Suppose you are well along on writing the next Pulitzer Prize winning novel. But you cannot figure out how you want it to end? In one scenario, the hero dies, and in another scenario the heroine dies. You might choose to make two copies of your novel in different directories and work on separate endings, eventually choosing one over the other. But let us suppose that in the course of doing this work in two different directories, you think of a great new way to develop your two characters in the early chapters. So now you need to make the same edits to both copies? Or maybe your novel is spread across several files, one per chapter, and you only need to edit a few early files in one version and copy just those files over to the other directory (hopefully not overwriting some other work there). This sounds a bit tedious, maybe complicated, and likely error-prone.
Let us see how git would handle this. Originally you are working on the main branch, almost always named master. Once ready to create two different endings, you would split off from master along two branches, perhaps named hero and heroine. You can now add material to each of the two different branches, switching between them at will. When you get your idea to improve the early character development, you can switch back to the master branch, edit your early chapters in a way that is common to both of your endings, then return to alternately working on your heroine and hero branches. You only ever have one copy of your early work, and if you ever make overlapping changes on your two branches, then there are procedures for managing those conflicts.
That example is a bit contrived, but basically realistic. And there is necessarily some hand-waving in how
git helps you. We will guide you carefully through a similar application of
git in
Checkpoint 2.2.1.
To use
git you need to author with source files that are simple text. So that likely means using some markup language like
LaTeX, MathBook XML, Markdown, reStructured Text, or a similar language such as those supported by
pandoc. XML formats for Word files might work out acceptably, but will be less than perfect. We are also going to show you how to use
git at the command-line in a terminal, so you might need to consult a tutorial on using a command-line and file management. We have some quickstart information on
git itself in
Appendix A.
git provides some powerful tools, and perhaps as a corollary, has a steep learning curve. There is no
right way to use
git, and the way you choose to employ it may in large part depend on social aspects of your project and its organization. We will organize our initial material according to the number of contributors and the organizational structure of the people in your project: solo contributor (
Chapter 2), a few collegial contributors (
Chapter 3), or many contributors with a central authority (
Chapter 4). Read all of these chapters, and read them in order, even if you know which model you might want to eventually employ. The techniques, concepts and principles build on each other, and there are no firm rules about numbers, procedures or organizational models. It is even possible they will fluctuate over the lifetime of a project.
We will distill some of the essential concepts of
git into a short series of eight
Principles, summarized in
Appendix F. Review them often, until you feel you understand them well, and it will be much easier to grasp the finer details of
git.
Principle 1.0.2. Git is a Tool.
git is a tool that can be adapted to many purposes and projects, in many different ways.
Discussions on the Internet about how best to use git can generate a lot of heat, but not much light. Ignore them. Understand the basic principles of how the tool functions, learn the commands that work for your projects, and employ it to make your real work more productive, efficient and enjoyable. Simply becoming a git expert is not the object.
You will find that git is like a garage door opener. Without one, you wonder why you might ever need one, but once you start using one, you decide you could not live without it. Or to extend the automotive motif, it is like a seat belt–you feel unsafe without it. Enjoy getting to know git.
