[PATCH] tutorial: prefix the prompts with names alice or bob, to make it clear who is doing what

[PATCH] tutorial: prefix the prompts with names alice or bob, to make it clear who is doing what

[Ian Katz]

---
 Documentation/gittutorial.txt |   26 +++++++++++++-------------
 1 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index e71b561..e4248b6 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -274,7 +274,7 @@ same machine, wants to contribute.
 Bob begins with:

 ------------------------------------------------
-$ git clone /home/alice/project myrepo
+bob$ git clone /home/alice/project myrepo
 ------------------------------------------------

 This creates a new directory "myrepo" containing a clone of Alice's
@@ -285,7 +285,7 @@ Bob then makes some changes and commits them:

 ------------------------------------------------
 (edit files)
-$ git commit -a
+bob$ git commit -a
 (repeat as necessary)
 ------------------------------------------------

@@ -293,8 +293,8 @@ When he's ready, he tells Alice to pull changes from the rep
ository
 at /home/bob/myrepo.  She does this with:

 ------------------------------------------------
-$ cd /home/alice/project
-$ git pull /home/bob/myrepo master
+alice$ cd /home/alice/project
+alice$ git pull /home/bob/myrepo master
 ------------------------------------------------

 This merges the changes from Bob's "master" branch into Alice's
@@ -312,7 +312,7 @@ again.  By defining 'remote' repository shorthand, you can m
ake
 it easier:

 ------------------------------------------------
-$ git remote add bob /home/bob/myrepo
+alice$ git remote add bob /home/bob/myrepo
 ------------------------------------------------

 With this, Alice can perform the first operation alone using the
@@ -320,7 +320,7 @@ With this, Alice can perform the first operation alone using
 the
 using:

 -------------------------------------
-$ git fetch bob
+alice$ git fetch bob
 -------------------------------------

 Unlike the longhand form, when Alice fetches from Bob using a
@@ -329,7 +329,7 @@ fetched is stored in a remote tracking branch, in this case
 `bob/master`.  So after this:

 -------------------------------------
-$ git log -p master..bob/master
+alice$ git log -p master..bob/master
 -------------------------------------

 shows a list of all the changes that Bob made since he branched from
@@ -339,14 +339,14 @@ After examining those changes, Alice
 could merge the changes into her master branch:

 -------------------------------------
-$ git merge bob/master
+alice$ git merge bob/master
 -------------------------------------

 This `merge` can also be done by 'pulling from her own remote
 tracking branch', like this:

 -------------------------------------
-$ git pull . remotes/bob/master
+alice$ git pull . remotes/bob/master
 -------------------------------------

 Note that git pull always merges into the current branch,
@@ -355,7 +355,7 @@ regardless of what else is given on the command line.
 Later, Bob can update his repo with Alice's latest changes using

 -------------------------------------
-$ git pull
+bob$ git pull
 -------------------------------------

 Note that he doesn't need to give the path to Alice's repository;
@@ -364,7 +364,7 @@ repository in the repository configuration, and that locatio
n is
 used for pulls:

 -------------------------------------
-$ git config --get remote.origin.url
+bob$ git config --get remote.origin.url
 /home/alice/project
 -------------------------------------

@@ -376,7 +376,7 @@ Git also keeps a pristine copy of Alice's master branch unde
r the
 name "origin/master":

 -------------------------------------
-$ git branch -r
+bob$ git branch -r
  origin/master
 -------------------------------------

@@ -384,7 +384,7 @@ If Bob later decides to work from a different host, he can s
till
 perform clones and pulls using the ssh protocol:

 -------------------------------------
-$ git clone alice.org:/home/alice/project myrepo
+bob$ git clone alice.org:/home/alice/project myrepo
 -------------------------------------

 Alternatively, git has a native protocol, or can use rsync or http;
--
1.5.3.7

Re: [PATCH] tutorial: prefix the prompts with names alice or bob, to make it clear who is doing what

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 293 bytes --]

On Thu, Jul 10, 2008 at 12:12:09PM -0400, Ian Katz <ifreecarve@gmail.com> wrote:
> ---
>  Documentation/gittutorial.txt |   26 +++++++++++++-------------
>  1 files changed, 13 insertions(+), 13 deletions(-)

Please add your Sign-off when sending patches, see
Documentation/SubmittingPatches.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] tutorial: prefix the prompts with names alice or bob, to make it clear who is doing what

[Ian Katz]

 Signed-off-by: Ian Katz <ifreecarve@gmail.com>

---
 Documentation/gittutorial.txt |   26 +++++++++++++-------------
 1 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index e71b561..e4248b6 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -274,7 +274,7 @@ same machine, wants to contribute.
 Bob begins with:

 ------------------------------------------------
-$ git clone /home/alice/project myrepo
+bob$ git clone /home/alice/project myrepo
 ------------------------------------------------

 This creates a new directory "myrepo" containing a clone of Alice's
@@ -285,7 +285,7 @@ Bob then makes some changes and commits them:

 ------------------------------------------------
 (edit files)
-$ git commit -a
+bob$ git commit -a
 (repeat as necessary)
 ------------------------------------------------

@@ -293,8 +293,8 @@ When he's ready, he tells Alice to pull changes from the rep
ository
 at /home/bob/myrepo.  She does this with:

 ------------------------------------------------
-$ cd /home/alice/project
-$ git pull /home/bob/myrepo master
+alice$ cd /home/alice/project
+alice$ git pull /home/bob/myrepo master
 ------------------------------------------------

 This merges the changes from Bob's "master" branch into Alice's
@@ -312,7 +312,7 @@ again.  By defining 'remote' repository shorthand, you can m
ake
 it easier:

 ------------------------------------------------
-$ git remote add bob /home/bob/myrepo
+alice$ git remote add bob /home/bob/myrepo
 ------------------------------------------------

 With this, Alice can perform the first operation alone using the
@@ -320,7 +320,7 @@ With this, Alice can perform the first operation alone using
 the
 using:

 -------------------------------------
-$ git fetch bob
+alice$ git fetch bob
 -------------------------------------

 Unlike the longhand form, when Alice fetches from Bob using a
@@ -329,7 +329,7 @@ fetched is stored in a remote tracking branch, in this case
 `bob/master`.  So after this:

 -------------------------------------
-$ git log -p master..bob/master
+alice$ git log -p master..bob/master
 -------------------------------------

 shows a list of all the changes that Bob made since he branched from
@@ -339,14 +339,14 @@ After examining those changes, Alice
 could merge the changes into her master branch:

 -------------------------------------
-$ git merge bob/master
+alice$ git merge bob/master
 -------------------------------------

 This `merge` can also be done by 'pulling from her own remote
 tracking branch', like this:

 -------------------------------------
-$ git pull . remotes/bob/master
+alice$ git pull . remotes/bob/master
 -------------------------------------

 Note that git pull always merges into the current branch,
@@ -355,7 +355,7 @@ regardless of what else is given on the command line.
 Later, Bob can update his repo with Alice's latest changes using

 -------------------------------------
-$ git pull
+bob$ git pull
 -------------------------------------

 Note that he doesn't need to give the path to Alice's repository;
@@ -364,7 +364,7 @@ repository in the repository configuration, and that locatio
n is
 used for pulls:

 -------------------------------------
-$ git config --get remote.origin.url
+bob$ git config --get remote.origin.url
 /home/alice/project
 -------------------------------------

@@ -376,7 +376,7 @@ Git also keeps a pristine copy of Alice's master branch unde
r the
 name "origin/master":

 -------------------------------------
-$ git branch -r
+bob$ git branch -r
   origin/master
 -------------------------------------

@@ -384,7 +384,7 @@ If Bob later decides to work from a different host, he can s
till
 perform clones and pulls using the ssh protocol:

 -------------------------------------
-$ git clone alice.org:/home/alice/project myrepo
+bob$ git clone alice.org:/home/alice/project myrepo
 -------------------------------------

 Alternatively, git has a native protocol, or can use rsync or http;
--
1.5.3.7

[PATCH] tutorial: clarify "pull" is "fetch + merge"

[Junio C Hamano]

The document says that a fetch with a configured remote stores what are
fetched in the remote tracking branches "Unlike the longhand form", but
there is no longhand form "fetch" demonstrated earlier.

This adds a missing demonstration of the longhand form, and a new
paragraph to explain why some people might want to fetch before pull.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 Documentation/gittutorial.txt |   28 +++++++++++++++++++++++++++-
 1 files changed, 27 insertions(+), 1 deletions(-)

diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index e71b561..38807f3 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -306,6 +306,32 @@ is the default.)
 The "pull" command thus performs two operations: it fetches changes
 from a remote branch, then merges them into the current branch.
 
+Note that in general, Alice would want her local changes committed before
+initiating this "pull".  If Bob's work conflicts with what Alice did since
+their histories forked, Alice will use her working tree and the index to
+resolve conflicts, and existing local changes will interfere with the
+conflict resolution process (git will still perform the fetch but will
+refuse to merge --- Alice will have to get rid of her local changes in
+some way and pull again when this happens).
+
+Alice can peek what Bob did without merging first, using the "fetch"
+command; this allows Alice to inspect what bob did, using a special
+symbol "FETCH_HEAD", in order to determine if he has anything worth
+pulling, like this:
+
+------------------------------------------------
+$ git fetch /home/bob/myrepo master
+$ git log -p ..FETCH_HEAD
+------------------------------------------------
+
+This operation is safe even if Alice has uncommitted local changes.
+
+After inspecting what Bob did, if there is nothing urgent, Alice may
+decide to continue working without pulling from Bob.  If Bob's history
+does have something Alice would immediately need, Alice may choose to
+stash her work-in-progress first, do a "pull", and then finally unstash
+her work-in-progress on top of the resulting history.
+
 When you are working in a small closely knit group, it is not
 unusual to interact with the same repository over and over
 again.  By defining 'remote' repository shorthand, you can make
@@ -315,7 +341,7 @@ it easier:
 $ git remote add bob /home/bob/myrepo
 ------------------------------------------------
 
-With this, Alice can perform the first operation alone using the
+With this, Alice can perform the first part of "pull" operation alone using the
 'git-fetch' command without merging them with her own branch,
 using:
 

Re: [PATCH] tutorial: clarify "pull" is "fetch + merge"

[Jeff King]

On Thu, Jul 10, 2008 at 02:01:57PM -0700, Junio C Hamano wrote:

> This adds a missing demonstration of the longhand form, and a new
> paragraph to explain why some people might want to fetch before pull.

A few English/typo nits below.

> +Alice can peek what Bob did without merging first, using the "fetch"

s/peek/& at/

> +command; this allows Alice to inspect what bob did, using a special

s/bob/\u&/

> -With this, Alice can perform the first operation alone using the
> +With this, Alice can perform the first part of "pull" operation alone using the

Should be either 'the "pull" operation' or 'a "pull" operation'.

-Peff