What is version control?

If you're already familiar with Git, you can save some reading by skipping ahead to the Creating a Git repo section. If not, here's a gentle introduction.

Even if you're the only person who works on a piece of source code (for example, Puppet manifests), it's still useful to be able to see what changes you made, and when. For example, you might realize that you introduced a bug at some point in the past, and you need to examine exactly when a certain file was modified and exactly what the change was. A version control system lets you do that, by keeping a complete history of the changes you've made to a set of files over time.

Tracking changes

When you're working on code with others, you also need a way to communicate with the rest of the team about your changes. A version control tool such as Git not only tracks everyone's changes, but lets you record a commit message, explaining what you did and why. The following example illustrates some aspects of a good commit message:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as
the subject of the commit and the rest of the text as the body.
The blank line separating the summary from the body is critical
(unless you omit the body entirely); various tools like `log`,
`shortlog`, and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Note

This example is taken from Chris Beams' excellent blog post on How to Write a Git Commit Message:

https://chris.beams.io/posts/git-commit/

Of course, you won't often need such a long and detailed message; most of the time, a single line will suffice. However, it's better to give more information than less.

Git also records when the change happened, who made it, what files were changed, added, or deleted, and which lines were added, altered, or removed. As you can imagine, if you're trying to track down a bug, and you can see a complete history of changes to the code, that's a big help. It also means you can, if necessary, roll back the state of the code to any point in history and examine it.

You might think this introduces a lot of extra complication. In fact, it's very simple. Git keeps out of your way until you need it, and all you have to do is write a commit message when you decide to record changes to the code.

Sharing code

A set of files under Git version control is called a repository, which is usually equivalent to a project. A Git repository (from now on, just repo) is also a great way to distribute your code to others, whether privately or publicly, so that they can use it, modify it, contribute changes back to you, or develop it in a different direction for their own requirements. The public GitHub repo for this book which we looked at in Chapter 1, Getting started with Puppet is a good example of this. You'll be able to use this repo for working through examples throughout the book, but you can also use it for help and inspiration when building Puppet manifests for your own infrastructure.

Because Git is so important for managing Puppet code, it's a good idea to get familiar with it, and the only way to do that is to use it for real. So let's start a new Git repo we can use to experiment with.