Skip to main content
\( \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)

Chapter1Introduction

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.

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 Exercise 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 , 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.

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.