@@ -2,9 +2,7 @@ Rather than diving into a sea of Git commands, use these elementary examples to get your feet wet. Despite their simplicity, each of them are useful. - -In fact, when I first started using Git, for months I never went beyond the -commands in this chapter. +Indeed, in my first months with Git I never ventured beyond the material in this chapter. === Saving State === basic.txt @@ -23,7 +23,7 @@ div.toc { padding: 0; padding-top: 0.5em; border: 0; - width: 13em; + width: 16em; background-color: #f9f9f9; margin-right:1em; @@ -34,7 +34,7 @@ div.content { padding: 0; /* won't match if font is smaller in toc */ - border-left: 13em solid #f9f9f9; + border-left: 16em solid #f9f9f9; padding-left: 1em; } book.css @@ -2,7 +2,9 @@ Instant branching and merging are the most lethal of Git's killer features. -*Problem*: External factors inevitably necessitate context switching. A severe bug manifests in the released version suddenly without warning, and must be fixed as soon as possible at all costs. The deadline for a certain feature is imminent. The guy who wrote a certain function is about to leave, so you should drop what you are doing and get him to help you understand it. +*Problem*: External factors inevitably necessitate context switching. A severe +bug manifests in the released version without warning. The deadline for a +certain feature is moved closer. A developer whose help you need for a key section of the project is about to leave. In all cases, you must abruptly drop what you are doing and focus on a completely different task. Interrupting your train of thought can be detrimental to your productivity, and the slower and less convenient it is to switch contexts, the greater the loss. With centralized version control we must download a fresh working copy from the central server. Distributed systems fare better, as we can clone the desired version locally. @@ -14,7 +16,7 @@ With this magic word, the files in your directory suddenly shapeshift from one v === The Boss Key === -Ever play one of those games where at the push of a button ("the boss key"), the screen would instantly display a spreadsheet or something? So if the boss walked in the office while you were playing the game you could quickly hide this fact? +Ever play one of those games where at the push of a button ("the boss key"), the screen would instantly display a spreadsheet or something? So if the boss walked in the office while you were playing the game you could quickly hide it away? In some directory: @@ -144,19 +146,19 @@ See *git help branch*. === Temporary Branches === -After a while you may realize that you are creating short-lived branches -frequently for the same reasons. Perhaps it seems every other time you create a -branch is just so you can save the current state while you briefly perform some -operation on the last saved state, such as fixing a high-priority bug. +After a while you may realize you are creating short-lived branches +frequently for similar reasons: every other branch merely serves to +save the current state so you can briefly hop back to an older state to +fix a high-priority bug or something. -It's analogous to changing the TV channel temporarily to see what else is on, -but instead of pushing a couple of buttons, you have to create, check out and -delete temporary branches and commits. Luckily, Git has a feature that +It's analogous to changing the TV channel temporarily to see what else is on. +But instead of pushing a couple of buttons, you have to create, check out and +delete temporary branches and commits. Luckily, Git has a shorcut that is as convenient as a TV remote control: $ git stash -This command saves the current state in a temporary location (a 'stash') and +This saves the current state in a temporary location (a 'stash') and restores the previous state. Your working directory appears exactly as it was before you started editing, and you can fix bugs, pull in upstream changes, and so on. When you want to go back to the stashed state, type: @@ -164,7 +166,7 @@ so on. When you want to go back to the stashed state, type: $ git stash apply # You may need to resolve some conflicts. You can have multiple stashes, and manipulate them in various ways. See -*git help stash*. +*git help stash*. As you may have guessed, Git maintains branches behind the scenes to perform this magic trick. === Work How You Want === branch.txt @@ -8,7 +8,7 @@ In Git and other distributed version control systems, cloning is the standard op This is the reason I first used Git. I can tolerate making tarballs or using *rsync* for backups and basic syncing. But sometimes I edit on my laptop, other times on my desktop, and the two may not have talked to each other in between. -Initialize a Git repository and commit your files as above on one machine. Then on the other: +Initialize a Git repository and commit your files on one machine. Then on the other: $ git clone other.computer:/path/to/files clone.txt @@ -1,6 +1,6 @@ == Lessons of History == -A consequence of the distributed nature of Git is that history can be edited +A consequence of Git's distributed nature is that history can be edited easily. But if you tamper with the past, take care: only rewrite that part of history which you alone possess. Just as nations forever argue over who committed what atrocity, if someone else has a clone whose version of history @@ -142,6 +142,50 @@ You can checkout the latest version of the project with: $ git checkout master . +=== Where Did It All Go Wrong? === + +You've just discovered a broken feature in your program which you know for sure was working a few months ago. Argh! Where did this bug come from? If only you had been testing the feature as you developed. + +It's too late for that now. However, provided you've been committing often, Git +can pinpoint the problem: + + $ git bisect start + $ git bisect bad SHA1_OF_BAD_VERSION + $ git bisect good SHA1_OF_GOOD_VERSION + +Git checks out a state halfway in between. Test the feature, and if it's still broken: + + $ git bisect bad + +If not, replace "bad" with "good". Git again transports you to a state halfway +between the known good and bad versions, narrowing down the possibilities. +After a few iterations, this binary search will lead you to the commit that +caused the trouble. Once you've finished your investigation, return to your +original state by typing: + + $ git bisect reset + +Instead of testing every change by hand, automate the search by running: + + $ git bisect run COMMAND + +Git uses the return value of the given command, typically a one-off script, to +decide whether a change is good or bad: the command should exit with code 0 +when good, 125 when the change should be skipped, and anything else between 1 +and 127 if it is bad. A negative return value aborts the bisect. + +You can do much more: the help page explains how to visualize bisects, examine +or replay the bisect log, and eliminate known innoncent changes for a speedier +search. + +=== Who Made It All Go Wrong? === + +Like many other version control systems, Git has a blame command: + + $ git blame FILE + +which annotates every line in the given file showing who last changed it, and when. Unlike many other version control systems, this operation works offline, reading only from local disk. + === Personal Experience === In a centralized version control system, history modification is a difficult history.txt @@ -12,7 +12,7 @@ But this will overwrite the old version. It's like those old school games which === Version Control === -When editing, you can "Save As..." a different file, or copy the file somewhere first before saving if you want to savour old versions. Maybe compress them too to save space. This is a primitive and labour-intensive form of version control. Computer games improved on this long ago, many of them providing multiple automatically timestamped save slots. +When editing, you can "Save As..." a different file, or copy the file somewhere first before saving if you want to savour old versions. You can compress them too to save space. This is a primitive and labour-intensive form of version control. Computer games improved on this long ago, many of them providing multiple automatically timestamped save slots. Let's make the problem slightly tougher. Say you have a bunch of files that go together, such as source code for a project, or files for a website. Now if you want to keep an old version you have to archive a whole directory. Keeping many versions around by hand is inconvenient, and quickly becomes expensive. intro.txt e85ebb8d1f38a21850b730d6dc88282f96f831b8 Ben Lynn benlynn@gmail.com http://github.com/blynn/gitmagic/commit/98a05572550e0e2d0eeb36f4a8b463a840c79885 98a05572550e0e2d0eeb36f4a8b463a840c79885 2008-11-30T14:01:08-08:00 2008-11-30T14:01:08-08:00 Described bisect and blame. 192f1cd1c581e76709601312b19a1376803251b2 Ben Lynn benlynn@gmail.com