Pro Git
Scott Chacon
July 29, 2009
Contents
1 Getting Started 1
1.1 About Version Control . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Local Version Control Systems . . . . . . . . . . . . . . . . . 1
1.1.2 Centralized Version Control Systems . . . . . . . . . . . . . 2
1.1.3 Distributed Version Control Systems . . . . . . . . . . . . . . 3
1.2 A Short History of Git . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Git Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.1 Snapshots, Not Differences . . . . . . . . . . . . . . . . . . . 4
1.3.2 Nearly Every Operation Is Local . . . . . . . . . . . . . . . . 5
1.3.3 Git Has Integrity . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.4 Git Generally Only Adds Data . . . . . . . . . . . . . . . . . 6
1.3.5 The Three States . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Installing Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.1 Installing from Source . . . . . . . . . . . . . . . . . . . . . 8
1.4.2 Installing on Linux . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.3 Installing on Mac . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.4 Installing on Windows . . . . . . . . . . . . . . . . . . . . . 9
1.5 First-Time Git Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5.1 Your Identity . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5.2 Your Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5.3 Your Diff Tool . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5.4 Checking Your Settings . . . . . . . . . . . . . . . . . . . . 11
1.6 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 Git Basics 13
2.1 Getting a Git Repository . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.1 Initializing a Repository in an Existing Directory . . . . . . . 13
2.1.2 Cloning an Existing Repository . . . . . . . . . . . . . . . . 14
2.2 Recording Changes to the Repository . . . . . . . . . . . . . . . . . 14
2.2.1 Checking the Status of Your Files . . . . . . . . . . . . . . . 14
2.2.2 Tracking New Files . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.3 Staging Modified Files . . . . . . . . . . . . . . . . . . . . . 16
2.2.4 Ignoring Files . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.5 Viewing Your Staged and Unstaged Changes . . . . . . . . . 18
2.2.6 Committing Your Changes . . . . . . . . . . . . . . . . . . . 21
2.2.7 Skipping the Staging Area . . . . . . . . . . . . . . . . . . . 22
i
PRO GIT SCOTT CHACON
2.2.8 Removing Files . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.9 Moving Files . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.3 Viewing the Commit History . . . . . . . . . . . . . . . . . . . . . . 24
2.3.1 Limiting Log Output . . . . . . . . . . . . . . . . . . . . . . 28
2.3.2 Using a GUI to Visualize History . . . . . . . . . . . . . . . 29
2.4 Undoing Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4.1 Changing Your Last Commit . . . . . . . . . . . . . . . . . . 29
2.4.2 Unstaging a Staged File . . . . . . . . . . . . . . . . . . . . 30
2.4.3 Unmodifying a Modified File . . . . . . . . . . . . . . . . . 31
2.5 Working with Remotes . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.5.1 Showing Your Remotes . . . . . . . . . . . . . . . . . . . . . 32
2.5.2 Adding Remote Repositories . . . . . . . . . . . . . . . . . . 33
2.5.3 Fetching and Pulling from Your Remotes . . . . . . . . . . . 34
2.5.4 Pushing to Your Remotes . . . . . . . . . . . . . . . . . . . . 34
2.5.5 Inspecting a Remote . . . . . . . . . . . . . . . . . . . . . . 34
2.5.6 Removing and Renaming Remotes . . . . . . . . . . . . . . . 35
2.6 Tagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.1 Listing Your Tags . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.2 Creating Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.3 Annotated Tags . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.6.4 Signed Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.6.5 Lightweight Tags . . . . . . . . . . . . . . . . . . . . . . . . 38
2.6.6 Verifying Tags . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.6.7 Tagging Later . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.6.8 Sharing Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.7 Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.7.1 Auto-Completion . . . . . . . . . . . . . . . . . . . . . . . . 41
2.7.2 Git Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3 Git Branching 43
3.1 What a Branch Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2 Basic Branching and Merging . . . . . . . . . . . . . . . . . . . . . 48
3.2.1 Basic Branching . . . . . . . . . . . . . . . . . . . . . . . . 48
3.2.2 Basic Merging . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.2.3 Basic Merge Conflicts . . . . . . . . . . . . . . . . . . . . . 53
3.3 Branch Management . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.4 Branching Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3.4.1 Long-Running Branches . . . . . . . . . . . . . . . . . . . . 56
3.4.2 Topic Branches . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.5 Remote Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.5.1 Pushing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.5.2 Tracking Branches . . . . . . . . . . . . . . . . . . . . . . . 63
3.5.3 Deleting Remote Branches . . . . . . . . . . . . . . . . . . . 63
3.6 Rebasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.6.1 The Basic Rebase . . . . . . . . . . . . . . . . . . . . . . . . 64
3.6.2 More Interesting Rebases . . . . . . . . . . . . . . . . . . . . 66
3.6.3 The Perils of Rebasing . . . . . . . . . . . . . . . . . . . . . 68
ii
CHAPTER 0 CONTENTS
3.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4 Git on the Server 71
4.1 The Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.1.1 Local Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.1.2 The SSH Protocol . . . . . . . . . . . . . . . . . . . . . . . 73
4.1.3 The Git Protocol . . . . . . . . . . . . . . . . . . . . . . . . 73
4.1.4 The HTTP/S Protocol . . . . . . . . . . . . . . . . . . . . . 74
4.2 Getting Git on a Server . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.2.1 Putting the Bare Repository on a Server . . . . . . . . . . . . 76
4.2.2 Small Setups . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.3 Generating Your SSH Public Key . . . . . . . . . . . . . . . . . . . . 77
4.4 Setting Up the Server . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.5 Public Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.6 GitWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.7 Gitosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.8 Git Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.9 Hosted Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.9.1 GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.9.2 Setting Up a User Account . . . . . . . . . . . . . . . . . . . 89
4.9.3 Creating a New Repository . . . . . . . . . . . . . . . . . . . 89
4.9.4 Importing from Subversion . . . . . . . . . . . . . . . . . . . 91
4.9.5 Adding Collaborators . . . . . . . . . . . . . . . . . . . . . . 92
4.9.6 Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.9.7 Forking Projects . . . . . . . . . . . . . . . . . . . . . . . . 95
4.9.8 GitHub Summary . . . . . . . . . . . . . . . . . . . . . . . . 96
4.10 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5 Distributed Git 97
5.1 Distributed Workflows . . . . . . . . . . . . . . . . . . . . . . . . . 97
5.1.1 Centralized Workflow . . . . . . . . . . . . . . . . . . . . . 97
5.1.2 Integration-Manager Workflow . . . . . . . . . . . . . . . . . 98
5.1.3 Dictator and Lieutenants Workflow . . . . . . . . . . . . . . 99
5.2 Contributing to a Project . . . . . . . . . . . . . . . . . . . . . . . . 100
5.2.1 Commit Guidelines . . . . . . . . . . . . . . . . . . . . . . . 100
5.2.2 Private Small Team . . . . . . . . . . . . . . . . . . . . . . . 102
5.2.3 Private Managed Team . . . . . . . . . . . . . . . . . . . . . 108
5.2.4 Public Small Project . . . . . . . . . . . . . . . . . . . . . . 111
5.2.5 Public Large Project . . . . . . . . . . . . . . . . . . . . . . 115
5.2.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
5.3 Maintaining a Project . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.3.1 Working in Topic Branches . . . . . . . . . . . . . . . . . . . 118
5.3.2 Applying Patches from E-mail . . . . . . . . . . . . . . . . . 118
5.3.3 Checking Out Remote Branches . . . . . . . . . . . . . . . . 121
5.3.4 Determining What Is Introduced . . . . . . . . . . . . . . . . 122
5.3.5 Integrating Contributed Work . . . . . . . . . . . . . . . . . 123
5.3.6 Tagging Your Releases . . . . . . . . . . . . . . . . . . . . . 128
5.3.7 Generating a Build Number . . . . . . . . . . . . . . . . . . 129
iii
PRO GIT SCOTT CHACON
5.3.8 Preparing a Release . . . . . . . . . . . . . . . . . . . . . . . 129
5.3.9 The Shortlog . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6 Git Tools 131
6.1 Revision Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.1.1 Single Revisions . . . . . . . . . . . . . . . . . . . . . . . . 131
6.1.2 Short SHA . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.1.3 A SHORT NOTE ABOUT SHA–1 . . . . . . . . . . . . . . 132
6.1.4 Branch References . . . . . . . . . . . . . . . . . . . . . . . 133
6.1.5 RefLog Shortnames . . . . . . . . . . . . . . . . . . . . . . 133
6.1.6 Ancestry References . . . . . . . . . . . . . . . . . . . . . . 134
6.1.7 Commit Ranges . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.2 Interactive Staging . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2.1 Staging and Unstaging Files . . . . . . . . . . . . . . . . . . 138
6.2.2 Staging Patches . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.3 Stashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.3.1 Stashing Your Work . . . . . . . . . . . . . . . . . . . . . . 141
6.3.2 Creating a Branch from a Stash . . . . . . . . . . . . . . . . 143
6.4 Rewriting History . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.4.1 Changing the Last Commit . . . . . . . . . . . . . . . . . . . 144
6.4.2 Changing Multiple Commit Messages . . . . . . . . . . . . . 145
6.4.3 Reordering Commits . . . . . . . . . . . . . . . . . . . . . . 147
6.4.4 Squashing a Commit . . . . . . . . . . . . . . . . . . . . . . 147
6.4.5 Splitting a Commit . . . . . . . . . . . . . . . . . . . . . . . 148
6.4.6 The Nuclear Option: filter-branch . . . . . . . . . . . . . . . 149
6.5 Debugging with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.5.1 File Annotation . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.5.2 Binary Search . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.6 Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.6.1 Starting with Submodules . . . . . . . . . . . . . . . . . . . 153
6.6.2 Cloning a Project with Submodules . . . . . . . . . . . . . . 155
6.6.3 Superprojects . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.6.4 Issues with Submodules . . . . . . . . . . . . . . . . . . . . 157
6.7 Subtree Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7 Customizing Git 163
7.1 Git Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.1.1 Basic Client Configuration . . . . . . . . . . . . . . . . . . . 164
7.1.2 Colors in Git . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.1.3 External Merge and Diff Tools . . . . . . . . . . . . . . . . . 166
7.1.4 Formatting and Whitespace . . . . . . . . . . . . . . . . . . 169
7.1.5 Server Configuration . . . . . . . . . . . . . . . . . . . . . . 170
7.2 Git Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.2.1 Binary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.2.2 Keyword Expansion . . . . . . . . . . . . . . . . . . . . . . 174
7.2.3 Exporting Your Repository . . . . . . . . . . . . . . . . . . . 176
iv
