Git Pocket Guide

Preface

What Is Git?

Git is a tool for tracking changes made to a set of files over time, a task traditionally known as “version control.” Although it is most often used by programmers to coordinate changes to software source code, and it is especially good at that, you can use Git to track any kind of content at all. Any body of related files evolving over time, which we’ll call a “project,” is a candidate for using Git. With Git, you can:

• Examine the state of your project at earlier points in time
• Show the differences among various states of the project
• Split the project development into multiple independent lines, called “branches,” which can evolve separately
• Periodically recombine branches in a process called “merging,” reconciling the changes made in two or more branches
• Allow many people to work on a project simultaneously, sharing and combining their work as needed

…and much more.

There have been many different version control systems developed in the computing world, including SCCS, RCS, CVS, Subversion, BitKeeper, Mercurial, Bazaar, Darcs, and others. Some particular strengths of Git are:

• Git is a member of the newer generation of distributed version control systems. Older systems such as CVS and Subversion are centralized, meaning that there is a single, central copy of the project content and history to which all users must refer. Typically accessed over a network, if the central copy is unavailable for some reason, all users are stuck; they cannot use version control until the central copy is working again. Distributed systems such as Git, on the other hand, have no inherent central copy. Each user has a complete, independent copy of the entire project history, called a “repository,” and full access to all version control facilities. Network access is only needed occasionally, to share sets of changes among people working on the same project.
• In some systems, notably CVS and Subversion, branches are slow and difficult to use in practice, which discourages their use. Branches in Git, on the other hand, are very fast and easy to use. Effective branching and merging allows more people to work on a project in parallel, relying on Git to combine their separate contributions.
• Applying changes to a repository is a two-step process: you add the changes to a staging area called the “index,” then commit those changes to the repository. The extra step allows you to easily apply just some of the changes in your current working files (including a subset of changes to a single file), rather than being forced to apply them all at once, or undoing some of those changes yourself before committing and then redoing them by hand. This encourages splitting changes up into better organized, more coherent and reusable sets.
• Git’s distributed nature and flexibility allow for many different styles of use, or “workflows.” Individuals can share work directly between their personal repositories. Groups can coordinate their work through a single central repository. Hybrid schemes permit several people to organize the contributions of others to different areas of a project, and then collaborate among themselves to maintain the overall project state.
• Git is the technology behind the enormously popular “social coding” website GitHub, which includes many well-known open source projects. In learning Git, you will open up a whole world of collaboration on small and large scales.

Goals of This Book

There are already several good books available on Git, including Scott Chacon’s Pro Git, and the full-size Version Control with Git by Jon Loeliger (O’Reilly). In addition, the Git software documentation (“man pages” on Unix) is generally well written and complete. So, why a Git Pocket Guide? The primary goal of this book is to provide a compact, readable introduction to Git for the new user, as well as a reference to common commands and procedures that will continue to be useful once you’ve already gotten some Git under your belt. The man pages are extensive and very detailed; sometimes, it’s difficult to peruse them for just the information you need for simple operations, and you may need to refer to several different sections to pull together the pieces you need. The two books mentioned are similarly weighty tomes with a wealth of detail. This Pocket Guide is task oriented, organized around the basic functions you need from version control: making commits, fixing mistakes, merging, searching history, and so on. It also contains a streamlined technical introduction whose aim is to make sense of Git generally and facilitate understanding of the operations discussed, rather than completeness or depth for its own sake. The intent is to help you become productive with Git quickly and easily.

Since this book does not aim to be a complete reference to all of Git’s capabilities, there are Git commands and functions that we do not discuss. We often mention these omissions explicitly, but some are tacit. Several more advanced features are just mentioned and described briefly so that you’re aware of their existence, with a pointer to the relevant documentation. Also, the sections that cover specific commands usually do not list every possible option or mode of operation, but rather the most common or useful ones that fit into the discussion at hand. The goal is simplicity and economy of explanation, rather than exhaustive detail. We do provide frequent references to various portions of the Git documentation, where you can find more complete information on the current topic. This book should be taken as an introduction, an aid to understanding, and a complement to the full documentation, rather than as a replacement for it.

At the time of this writing in early 2013, Git is undergoing rapid development; new versions appear regularly with new features and changes to existing ones, so expect that by the time you read this, some alterations will already have occurred; that’s just the nature of technical writing. This book describes Git as of version 1.8.2.

Conventions Used in This Book

Here are a few general remarks and conventions to keep in mind while reading this book.

Unix

Git was created in the Unix environment, originally in fact both for and by people working on the core of the Linux operating system. Though it has been ported to other platforms, it is still most popular on Unix variants, and its commands, design, and terminology all strongly reflect its origin. Especially in a Pocket Guide format, it would be distracting to have constant asides on minor differences with other platforms, so for simplicity and uniformity, this book assumes Unix generally in its descriptions and choice of examples.

Shell

All command-line examples are given using the bash shell syntax. Git uses characters that are special to bash and other shells as well, such as *, ~, and ?. Remember that you will need to quote these in order to prevent the shell from expanding them before Git sees them. For example, to see a log of changes pertaining to all C source files, you need something like this:

$ git log -- '*.c'

and not this:

$ git log -- *.c

The latter is unpredictable, as the shell will try to expand *.c in the current context. It might do any number of things; few of them are likely to be what you want.

The examples given in the book use such quoting as necessary.

Command Syntax

We employ common Unix conventions for indicating the syntax of commands, including:

• --{foo,bar} indicates the options --foo and --bar.
• Square brackets indicate an optional element that may appear or not; e.g., --where[=location] means that you may either use --where by itself (with some default location) or give a specific location, perhaps --where=Boston.

Typography

The following typographical conventions are used in this book:

Italic

Indicates new terms; also, Git branches are normally given in italic, as opposed to other names such as tags and commit IDs, which are given in constant width. Titles to Unix man pages are also given in italics.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

These lines signify a tip, warning, caution, or general note.

Using Code Examples

This book is here to help you get your job done. In general, if this book includes code examples, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Git Pocket Guide by Richard E. Silverman (O’Reilly). Copyright 2013 Richard Silverman, 978-1-449-32586-2.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of product mixes and pricing programs for organizations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and dozens more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://oreil.ly/git_pocket_guide.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

I gratefully acknowledge the support and patience of everyone at O’Reilly involved in creating this book, especially my editors Meghan Blanchette and Mike Loukides, during a book-writing process with a few unexpected challenges along the way. I would also like to thank my technical reviewers: Robert G. Byrnes, Max Caceres, Robert P. J. Day, Bart Massey, and Lukas Toth. Their attention to detail and thoughtful criticism have made this a much better book than it would otherwise have been. All errors that survived their combined assault are mine and mine alone.

I dedicate this book to the memory of my grandmother, Eleanor Gorsuch Jefferies (19 May 1920–18 March 2012).

Richard E. Silverman

New York City, 15 April 2013