From 3f5de7128f9fd8c5d45d42bc24fc0f993f7da0e1 Mon Sep 17 00:00:00 2001
From: Ben Lynn <benlynn@gmail.com>
Date: Tue, 20 May 2008 00:40:09 -0700
Subject: [PATCH] Intro edits.

---
 basic.txt       |  6 +++---
 clone.txt       |  4 ++--
 grandmaster.txt |  6 +++---
 intro.txt       | 14 +++++++++-----
 4 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/basic.txt b/basic.txt
index 4d310f1..ca39b9d 100644
--- a/basic.txt
+++ b/basic.txt
@@ -6,12 +6,12 @@ Rather than diving into a sea of Git commands, use these elementary examples to
 
 When I'm about to attempt something drastic I like to save the current state, so I can go back and try again should things go awry.
 
+Take a snapshot of all files in the current directory with:
+
  $ git init
  $ git add .
  $ git commit -m "My first backup"
 
-to take a snapshot of all files in the current directory.
-
 The above sequence of commands should be memorized, or placed in a script, as they will be reused frequently.
 
 Then if something goes wrong, run:
@@ -62,7 +62,7 @@ This alternate reality is called a ''branch'', and <<branch,we'll have more to s
 
 will take you back to the present.
 
-Note uncommitted changes will travel in time with you when you use the checkout command.
+Uncommitted changes travel in time with you when you run checkout.
 
 To take the computer game analogy again:
 
diff --git a/clone.txt b/clone.txt
index 207c579..2a234f4 100644
--- a/clone.txt
+++ b/clone.txt
@@ -40,7 +40,7 @@ Initialize a Git repository for your files:
 On the central server, initialize an empty Git repository with some name,
 and start the Git daemon if necessary:
 
- $ GIT_DIR==proj.git git init
+ $ GIT_DIR=proj.git git init
  $ git daemon --detach  # it might already be running
 
 Some public hosts, such as http://repo.or.cz[repo.or.cz], will have a different method for setting up the initially empty Git repository, such as filling in a form on a webpage.
@@ -69,7 +69,7 @@ Sick of the way a project is being run? Think you could do a better job? Then on
 
  $ git clone git://main.server/path/to/files
 
-Next tell everyone to check out your fork of the project at your server.
+Next tell everyone about your fork of the project at your server.
 
 At any later time, you can merge in the changes from the original project with:
 
diff --git a/grandmaster.txt b/grandmaster.txt
index 109412d..3a2c40a 100644
--- a/grandmaster.txt
+++ b/grandmaster.txt
@@ -61,7 +61,7 @@ Did you just commit, but wish you had typed a different message? Realized you fo
 
 can help you out.
 
-Since this changes the history, only do this if you have yet to push your changes, otherwise your tree will diverge from other trees. Of course, if you control all the other trees too, then there is no problem since you can always overwrite them.
+Since this changes the history, only do this if you have yet to push your changes, otherwise your tree will diverge from other trees. Of course, if you control all the other trees too, then there is no problem since you can overwrite them.
 
 === ... And Then Some ===
 
@@ -131,13 +131,13 @@ But suppose you never took it down? Don't worry, for commands like these, Git sa
 
 Perhaps ORIG_HEAD isn't enough. Perhaps you've just realized you made a monumental mistake last month and you need to go back to an ancient commit in a long-forgotten branch.
 
-It's hard to lose Git commits permanently, even after deleting branches. As long as you never run git gc, your commits are preserved forever and can be restored at any time.
+It's hard to lose Git commits permanently, even after deleting branches. As long as you never run *git gc \--prune*, your commits are preserved forever and can be restored at any time.
 
 The trouble is finding the appropriate hash. You could look at all the hash values in `.git/objects` and use trial and error to find the one you want. But there's a much easier way.
 
 Git records every hash of a commit it computes in `.git/logs`. The subdirectory `refs` contains the history of all activity on all branches, while the file `HEAD` shows every hash value it has ever taken. The latter can be used to find hashes of commits on branches that have been accidentally lopped off.
 
-Eventually, you may want to run git gc to recover space. Be aware that doing so prevents you from recovering lost HEADs.
+Eventually, you may want to run *git gc \--prune* to recover space. Be aware that doing so prevents you from recovering lost HEADs.
 
 === Building On Git ===
 
diff --git a/intro.txt b/intro.txt
index a65e217..762d7a6 100644
--- a/intro.txt
+++ b/intro.txt
@@ -38,16 +38,20 @@ This initial cloning operation can be expensive, especially if there's a long hi
 
 ==== A Silly Superstition ====
 
-A popular misconception is that distributed systems are ill-suited for projects requiring an official central repository (see for example http://www.subversionary.org/martintomes/git[this blog post]). Nothing could be further from the truth. Photographing someone does not cause their soul to be stolen. Similarly, cloning the master repository does not diminish its importance.
+A popular misconception is that distributed systems are ill-suited for projects requiring an official central repository. Nothing could be further from the truth. Photographing someone does not cause their soul to be stolen. Similarly, cloning the master repository does not diminish its importance.
 
-A good first approximation is that anything a centralized version control system can do, a well-designed distributed system can do better. While not strictly true, one is less likely to make erroneous comparisons with this rule of thumb.
+A good first approximation is that anything a centralized version control system can do, a well-designed distributed system can do better. Network resources are simply costlier than local resources. While we shall later see there are drawbacks to a distributed approach, one is less likely to make erroneous comparisons with this rule of thumb.
 
-You might not use most features of such a system in a small project, but there is nothing wrong with this as there is negligible overhead. Moreover, your project may grow beyond your original expectations. It's like carrying a Swiss army knife even though you mostly use it to open bottles. On the day you desperately need a screwdriver you'll be glad you haven't been carrying a plain bottle-opener all this time.
+A small project may only need a fraction of the features offered by such a system. But would you use Roman numerals when calculating with small numbers? Moreover, your project may grow beyond your original expectations. Using Git from the outset is like carrying a Swiss army knife even though you mostly use it to open bottles. On the day you desperately need a screwdriver you'll be glad you have more than a plain bottle-opener.
 
 === Merge Conflicts ===
 
 An interesting problem arises in any type of revision control system. Suppose Alice and Bob have both independently downloaded the latest saved game. They both play the game a bit more and save. What if they both want to submit their new saves? Let's say Alice uploads first. Then when Bob tries to upload his save, the system realizes that his state does not chronologically follow Alice's state.
 
-Ideally, the team possesses some sort of tool that can merge together progress from two different saved games into a new saved game. With such a tool, the problem is solved because Bob can merge Alice's state into his, and then upload the result. But in general, there is no such tool that can handle all cases and sometimes the only solution is human intervention.
+Let us revert to editing a text file. Our computer game analogy becomes too thinly stretched since most games never worry about this.
 
-Many revision control systems can automatically sort out simple merge conflicts with text files, and will ask a human to help if they cannot resolve the problem themselves.
+So suppose Alice has inserted a line at the beginning of a file, and Bob appends one at the end. They both upload their changes. Most systems will automatically deduce a reasonable course of action: accept and merge their changes, so both Alice's and Bob's edits are applied.
+
+Now suppose both Alice and Bob have both made distinct edits to the same line. Then it is impossible to resolve the conflict without human intervention. The second person to upload is informed of a merge conflict, and they must either choose one edit over another, or revise the line entirely.
+
+More complex situations can arise. Version control systems handle the simpler cases themselves, and leave the difficult cases for humans. Usually their behaviour is configurable.
-- 
2.11.4.GIT