Pro Git

CYAN MAGENTA

YELLOW BLACK PANTONE 123 C

w

BOOKS FOR PROFESSIONALS BY PROFESSIONALS®

THE EXPERT’S VOICE® IN SOFTWARE DEVELOPMENT Companion eBook Available

Pro Git

Git

Pro Git is written to help the professional developer learn the Git distributed source control tool from front to back. In this book, you’ll learn why Git is different and powerful, how to use it from beginning usage to advanced features, how to transition to it from an existing system, and how it works under the covers. The book will also help you master a variety of common workflows, both as a contributor to a Git-based project and as a maintainer of such a project. This book assumes no prior knowledge of Git but will make you an expert, ready to dazzle your friends and impress your coworkers. I wrote Pro Git because I teach Git and talk to people all the time who want to learn to use it. Many of them have heard from their peers how great Git is, but I get only an hour or two to try to convince them why the tool is so amazing. This is the in-depth guide I want people to be able to learn from after they have caught the bug. Git is such a huge change from other tools that I feel I became a better programmer after learning it. I want to help you learn it too, perhaps a bit more easily than I did. Git is an incredible tool that will not only make you think about source control differently but also make you a better developer. Using the lightweight branching system to do fast and cheap context switching when you develop will change how you approach programming problems by removing obstacles to development that you shouldn’t have to deal with. I hope this book makes it easier for you to learn Git and feel comfortable using it. I also hope Git changes the way you approach your source-code development tasks, as it did for me.

Pro

Dear Reader,

Pro Git

Sincerely,

Everything you need to know about the Git distributed source control tool

Scott Chacon

See last page for details on $10 eBook version

RELATED TITLES

Companion eBook

+++

)3".        

US $34.99

Chacon

Available online at http://progit.org

+++

Scott Chacon Foreword by Junio C Hamano, Git project leader

Shelve in Software Development User level: Beginner–Advanced

  

this print for content only—size & color not accurate

spine = 0.6563" 288 page count

Pro Git

Scott Chacon

Pro Git Copyright © 2009 by Scott Chacon Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Apress (dppl6++sss*]lnaoo* _ki+) and the author(s) ask for your support by buying the print or eBook edition through any online or retail outlet. A copy of the license is included in the section entitled “Creative Commons Legal Code.” All rights reserved subject to the Creative Commons license. ISBN-13 (pbk): 978-1-4302-1833-3 ISBN-13 (electronic): 978-1-4302-1834-0 Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1 The Git logo on this book’s cover comes from dppl6++aj*segela`e]*knc+sege+Beha6Cep)hkck*orc, where it is available under the GNU General Public License. It is available from dppl6++]lnaoo*_ki+^kkg+reas+ -0/,.-4//5. You may redistribute it and/or modify it under the terms of the GPL (dppl6++sss*cjq*knc+ _kluhabp+clh*dpih), as published by the Free Software Foundation; either version 2 of the License, or any later version. Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. Lead Editor: Duncan Parkes Technical Reviewer: Shawn Pearce Editorial Board: Clay Andres, Steve Anglin, Mark Beckner, Ewan Buckingham, Tony Campbell, Gary Cornell, Jonathan Gennick, Michelle Lowman, Matthew Moodie, Jeffrey Pepper, Frank Pohlmann, Ben Renow-Clarke, Dominic Shakeshaft, Matt Wade, Tom Welsh Project Managers: Beth Christmas, Candace English Copy Editor: Tiffany Taylor Associate Production Director: Kari Brooks-Copony Production Editor: Liz Berry Compositor: Diana Van Winkle Proofreader: Dan Shaw Indexer: Julie Grady Cover Designer: Anna Ishchenko Manufacturing Director: Tom Debolski Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail kn`ano)jumteT-jGdTlD=VoI_eHm4R2NfoJ=Ms`o`IBrOhRG+3T= p/B]kFk=oj_I-M5t1'/R,Ss24+aEBi^-vqQBhfMFGlnnT44TulJ@rfUJ^u2rs+L^,nsanp+Aj iV'=S0KVLjPLE45VLiRIHq]un@._A42V+eh4^'cs/n/'-jG]piEgfj.ok-`,-Mn]PhImROo^t JnNBe5snb'I3M99o_d]_kj/Jv]?-u_.A====@=M=>===>=M?>,,3j+ss'kqJ0cOHGooItTj>Krb5HCp0H kfC2no2dL>,5f5N+P-3+t0hdF=,B/BN-nL2gU>NoSf.]PdCs2DTHi5+1vupG2Vpc/NLGG'0g Ufd210-JUojA=VqTv,fPPu=QbnpQ/V1A,,/?0ktKf2D,nbEB-gGE5I=MHI`lCS-CUAEcO5Av O`b`4=_?Ee_P@S^mH=_Q0Qlg]T4GuChHsoJqqCvpk^B4i3.=H?+jHB2FHpLkbsB>hc_'iuer K3P?QO>`HMhcIRKBm-E.qLSMKgKSM=DqgAKibfu.f_ptO@>M..,uif]JoDP0gcpVc.=UUcLm `=r4FccFE?Qr]t.P5r]1coc)gaul]en You append them to your ]qpdkneva`[gauo file: _]p+pil+e`[no]*fkdj*lq^::z+*ood+]qpdkneva`[gauo _]p+pil+e`[no]*fkoea*lq^::z+*ood+]qpdkneva`[gauo _]p+pil+e`[no]*faooe_]*lq^::z+*ood+]qpdkneva`[gauo Now, you can set up an empty repository for them by running cepejep with the ))^]na option, which initializes the repository without a working directory: _`+klp+cep ig`enlnkfa_p*cep _`lnkfa_p*cep cep))^]naejep Then, John, Josie, or Jessica can push the first version of their project into that repository by adding it as a remote and pushing up a branch. Note that someone must shell onto the machine and create a bare repository every time you want to add a project. Let’s use cepoanran as the hostname of the server on which you’ve set up your “git” user and repository. If you’re running it internally, and you set up DNS for cepoanran to point to that server, then you can use the commands pretty much as is: kjFkdjo_kilqpan _`iulnkfa_p cepejep cep]``* cep_kiiep)i#ejepe]h_kiiep# cepnaikpa]``knecejcep Now, Jessica makes a couple of commits on the ba]pqna> branch: reihe^+oeilhacep*n^ cep_kiiep)]i#i]`apdaho)pnaabqj_pekjna_qnoera# Wba]pqna>a1^,b`_Yi]`apdaho)pnaabqj_pekjna_qnoera -behao_d]jca`(-ejoanpekjo$'%(-`ahapekjo$)% reihe^+oeilhacep*n^ cep_kiiep)]i#]``ho)behao# Wba]pqna>41-.35-Y]``ho)behao -behao_d]jca`(1ejoanpekjo$'%(,`ahapekjo$)%

119

120

CH APT ER 5 N DIS TR IB U TED G IT

Jessica’s repository looks like Figure 5-12.

Figure 5-12. Jessica’s initial commit history She’s ready to push up her work, but she gets an e-mail from Josie that a branch with some initial work on it was already pushed to the server as ba]pqna>aa. Jessica first needs to merge those changes in with her own before she can push to the server. She can then fetch Josie’s changes down with cepbap_d: cepbap_dknecej *** Bnkifaooe_]aa):knecej+ba]pqna>aa Jessica can now merge this into the work she did with cepianca: cepiancaknecej+ba]pqna>aa =qpk)iancejche^+oeilhacep*n^ Iancai]`a^una_qnoera* he^+oeilhacep*n^x0'''' -behao_d]jca`(0ejoanpekjo$'%(,`ahapekjo$)% There is a bit of a problem—she needs to push the merged work in her ba]pqna> branch to the ba]pqna>aa branch on the server. She can do so by specifying the local branch followed by a colon (6) followed by the remote branch to the ceplqod command: ceplqodknecejba]pqna>6ba]pqna>aa *** Pkfaooe_]):ba]pqna>aa

C H A P T E R 5 N D I S T R I B U T E D G I T

This is called a refspec. See Chapter 9 for a more detailed discussion of Git refspecs and different things you can do with them. Next, John e-mails Jessica to say he’s pushed some changes to the ba]pqna= branch and ask her to verify them. She runs a cepbap_d to pull down those changes: cepbap_dknecej *** Bnkifaooe_]x-3/Ge>+o(`kja* Naokhrejc`ahp]o6-,,!$-51-+-51-%(`kja* Oq^ik`qhal]pd#n]_g#6_da_ga`kqp#,4`3,5b34^4_1^,b^a^34.-a/3b]1/a25]b_b0//# Now your n]_g subdirectory is at the exact state it was in when you committed earlier. If another developer makes changes to the n]_g code and commits, and you pull that reference down and merge it in, you get something a bit odd: cepiancaknecej+i]opan Ql`]pejc,11,.3-**41]/aaa

167

168

CH APT ER 6 N G IT TOOL S

B]opbkns]n` n]_gx.') -behao_d]jca`(-ejoanpekjo$'%(-`ahapekjo$)% Wi]opan&Y cepop]pqo Kj^n]j_di]opan ?d]jca`^qpjkpql`]pa`6 $qoacep]``8beha:***pkql`]pasd]psehh^a_kiieppa`% $qoacep_da_gkqp))8beha:***pk`eo_]n`_d]jcaoejskngejc`ena_pknu%  ik`ebea`6n]_g  You merged in what is basically a change to the pointer for your submodule; but it doesn’t update the code in the submodule directory, so it looks like you have a dirty state in your working directory: cep`ebb `ebb))cep]+n]_g^+n]_g ej`at2_1a3,^**,4`3,5b-2,,,, )))]+n]_g '''^+n]_g qbbannqjpeia]j`pdaLnkpk_kh .pailkn]h>qbban_kilehan$lnkpk_%ata_qpapdabkhhksejc6 .pailkn]h Again, it doesn’t show commits that you did locally in Git or that have been pushed to Subversion in the meantime.

SVN Server Information You can also get the same sort of information that orjejbk gives you by running ceporj ejbk: ceporjejbk L]pd6* QNH6dpplo6++o_d]_kj)paop*ckkcha_k`a*_ki+orj+pnqjg NalkoepknuNkkp6dpplo6++o_d]_kj)paop*ckkcha_k`a*_ki+orj NalkoepknuQQE@60_5/^.14)/3/b)--`a)^a,1)1b3]42.24,.5 Nareoekj643

211

212

CH APT ER 8 N G IT A ND OTHER S YS TEMS

Jk`aGej`6`ena_pknu O_da`qha6jkni]h H]op?d]jca`=qpdkn6o_d]_kj H]op?d]jca`Nar643 H]op?d]jca`@]pa6.,,5),1),.-26,36/3),3,,$O]p(,.I]u.,,5% This is like ^h]ia and hkc in that it runs offline and is up to date only as of the last time you communicated with the Subversion server.

Ignoring What Subversion Ignores If you clone a Subversion repository that has orj6ecjkna properties set anywhere, you’ll likely want to set corresponding *cepecjkna files so you don’t accidentally commit files that you shouldn’t. ceporj has two commands to help with this issue. The first is ceporj _na]pa) ecjkna, which automatically creates corresponding *cepecjkna files for you so your next commit can include them. The second command is ceporj odks)ecjkna, which prints to stdout the lines you need to put in a *cepecjkna file so you can redirect the output into your project at_hq`a file: ceporjodks)ecjkna:*cep+ejbk+at_hq`a That way, you don’t litter the project with *cepecjkna files. This is a good option if you’re the only Git user on a Subversion team, and your teammates don’t want *cepecjkna files in the project.

Git-Svn Summary The ceporj tools are useful if you’re stuck with a Subversion server for now or are otherwise in a development environment that necessitates running a Subversion server. You should consider it crippled Git, however, or you’ll hit issues in translation that may confuse you and your collaborators. To stay out of trouble, try to follow these guidelines:

s +EEPALINEAR'ITHISTORYTHATDOESNTCONTAINMERGECOMMITSMADEBYcepianca. Rebase any work you do outside of your mainline branch back onto it; don’t merge it in.



s $ONTSETUPANDCOLLABORATEONASEPARATE'ITSERVER0OSSIBLYHAVEONETOSPEEDUP clones for new developers, but don’t push anything to it that doesn’t have a cep)orj)e` entry. You may even want to add a pre-receive hook that checks each commit message for a cep)orj)e` and rejects pushes that contain commits without it.

If you follow those guidelines, working with a Subversion server can be more bearable. However, if it’s possible to move to a real Git server, doing so can gain your team a lot more.

Migrating to Git If you have an existing codebase in another VCS but you’ve decided to start using Git, you must migrate your project one way or another. This section goes over some importers that are included with Git for common systems and then demonstrates how to develop your own custom importer.

C H A P T E R 8 N G I T A N D O T H E R S Y S T E M S

Importing You’ll learn how to import data from two of the bigger professionally used SCM systems— Subversion and Perforce—both because they make up the majority of users I hear of who are currently switching, and because high-quality tools for both systems are distributed with Git.

Subversion If you read the previous section about using ceporj, you can easily use those instructions to ceporj_hkja a repository; then, stop using the Subversion server, push to a new Git server, and start using that. If you want the history, you can accomplish that as quickly as you can pull the data out of the Subversion server (which may take a while). However, the import isn’t perfect; and because it will take so long, you may as well do it right. The first problem is the author information. In Subversion, each person committing has a user on the system who is recorded in the commit information. The examples in the previous section show o_d]_kj in some places, such as the ^h]ia output and the ceporj log. If you want to map this to better Git author data, you need a mapping from the Subversion users to the Git authors. Create a file called qoano*ptp that has this mapping in a format like this: o_d]_kj9O_kpp?d]_kj8o_d]_kj ))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))) l]_g[nalknp6capl]caoeva$%90,52 l]_g[nalknp6_kna*l]_ga`CepSej`ksOeva9//1100/. l]_g[nalknp6_kna*l]_ga`CepHeiep9.240/1012 l]_g[nalknp6l]_g[qoa`[_pn95 l]_g[nalknp6l]_g[ii]l[_]hho91 l]_g[nalknp6l]_g[klaj[sej`kso9-+l]_g[nalknp6l]_g[i]lla`9-/12+-/12 ))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))) As you can see, when it completes successfully, it gives you a bunch of statistics about what it accomplished. In this case, you imported 18 objects total for 5 commits into 1 branch. Now, you can run cephkc to see your new history: cephkc). _kiiep-,^ba3`.._a-1aa.1^2,]4.0_454.-13_]15/`0=qpdkn6O_kpp?d]_kj8o_d]_kj