[PATCH] Documentation/tutorial: misc updates

[PATCH] Documentation/tutorial: misc updates

[Santi Béjar]

Three changes:
1) Teach how to delete a branch with "git branch -d name".
2) The first commit does not have a parent.
3) Teach "git show" instead of "git cat-file -p".
---
 Documentation/tutorial.txt |   17 +++++++++++++----
 1 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index d043e84..f0a5526 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -222,6 +222,15 @@ $ gitk
 
 will show a nice graphical representation of the resulting history.
 
+At this point you could delete the experimental branch with
+
+------------------------------------------------
+$ git branch -d experimental
+------------------------------------------------
+
+This command ensures that the changes in the experimental branch are
+already in the current branch.
+
 If you develop on a branch crazy-idea, then regret it, you can always
 delete the branch with
 
@@ -391,8 +400,8 @@ $ git show HEAD		# the tip of the current branch
 $ git show experimental	# the tip of the "experimental" branch
 -------------------------------------
 
-Every commit has at least one "parent" commit, which points to the
-previous state of the project:
+Every commit has at least one "parent" commit (except the first),
+which points to the previous state of the project:
 
 -------------------------------------
 $ git show HEAD^  # to see the parent of HEAD
@@ -510,10 +519,10 @@ of the file:
 $ git diff v2.5:Makefile HEAD:Makefile.in
 -------------------------------------
 
-You can also use "git cat-file -p" to see any such file:
+You can also use "git show" to see any such file:
 
 -------------------------------------
-$ git cat-file -p v2.5:Makefile
+$ git show v2.5:Makefile
 -------------------------------------
 
 Next Steps
-- 
1.5.0.rc0.g91ea

Re: [PATCH] Documentation/tutorial: misc updates

[Horst H. von Brand]

Santi Béjar <sbejar@gmail.com> wrote:
> Three changes:
> 1) Teach how to delete a branch with "git branch -d name".
> 2) The first commit does not have a parent.
> 3) Teach "git show" instead of "git cat-file -p".
> ---
>  Documentation/tutorial.txt |   17 +++++++++++++----
>  1 files changed, 13 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
> index d043e84..f0a5526 100644
> --- a/Documentation/tutorial.txt
> +++ b/Documentation/tutorial.txt
> @@ -222,6 +222,15 @@ $ gitk
>  
>  will show a nice graphical representation of the resulting history.
>  
> +At this point you could delete the experimental branch with
> +
> +------------------------------------------------
> +$ git branch -d experimental
> +------------------------------------------------
> +
> +This command ensures that the changes in the experimental branch are
> +already in the current branch.
> +

Huh? This deletes the branch, it doesn't ensure changes have been saved.

>  If you develop on a branch crazy-idea, then regret it, you can always
>  delete the branch with
>  
> @@ -391,8 +400,8 @@ $ git show HEAD		# the tip of the current branch
>  $ git show experimental	# the tip of the "experimental" branch
>  -------------------------------------
>  
> -Every commit has at least one "parent" commit, which points to the
> -previous state of the project:
> +Every commit has at least one "parent" commit (except the first),
> +which points to the previous state of the project:

And how can it have more than one parent? If you mention it, better come
clean about merges (can be explained in detail later).

>  -------------------------------------
>  $ git show HEAD^  # to see the parent of HEAD

And if there are several parents?

> @@ -510,10 +519,10 @@ of the file:
>  $ git diff v2.5:Makefile HEAD:Makefile.in
>  -------------------------------------

HEAD:Makefile.in doesn't need HEAD.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Re: [PATCH] Documentation/tutorial: misc updates

[Jakub Narebski]

Horst H. von Brand wrote:

>> +------------------------------------------------
>> +$ git branch -d experimental
>> +------------------------------------------------
>> +
>> +This command ensures that the changes in the experimental branch are
>> +already in the current branch.
>> +
> 
> Huh? This deletes the branch, it doesn't ensure changes have been saved.

It ensures that the branch we want to delete is in lineage of
current branch (otherwise we would have to use -D).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation/tutorial: misc updates

[Horst H. von Brand]

Jakub Narebski <jnareb@gmail.com> wrote:
> Horst H. von Brand wrote:
> 
> >> +------------------------------------------------
> >> +$ git branch -d experimental
> >> +------------------------------------------------
> >> +
> >> +This command ensures that the changes in the experimental branch are
> >> +already in the current branch.
> >> +

> > Huh? This deletes the branch, it doesn't ensure changes have been saved.

> It ensures that the branch we want to delete is in lineage of
> current branch (otherwise we would have to use -D).

I know. But it doesn't "ensure" anything, the /user/ has to ensure
beforehand that there are no outstanding changes for it to succeed. Fine
distinction, I know. But better be extra clear.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Re: [PATCH] Documentation/tutorial: misc updates

[Santi Béjar]

On 1/3/07, Horst H. von Brand <vonbrand@inf.utfsm.cl> wrote:
> Santi Béjar <sbejar@gmail.com> wrote:
> > Three changes:
> > 1) Teach how to delete a branch with "git branch -d name".
> > 2) The first commit does not have a parent.
> > 3) Teach "git show" instead of "git cat-file -p".
> > ---
> >  Documentation/tutorial.txt |   17 +++++++++++++----
> >  1 files changed, 13 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
> > index d043e84..f0a5526 100644
> > --- a/Documentation/tutorial.txt
> > +++ b/Documentation/tutorial.txt
> > @@ -222,6 +222,15 @@ $ gitk
> >
> >  will show a nice graphical representation of the resulting history.
> >
> > +At this point you could delete the experimental branch with
> > +
> > +------------------------------------------------
> > +$ git branch -d experimental
> > +------------------------------------------------
> > +
> > +This command ensures that the changes in the experimental branch are
> > +already in the current branch.
> > +
>
> Huh? This deletes the branch, it doesn't ensure changes have been saved.

It deletes the branch only if the current branch is fast-forwarding it.

Could be rephrase as:

This command only delete the experimental branch if it is already
merge in the current branch.

>
> >  If you develop on a branch crazy-idea, then regret it, you can always
> >  delete the branch with
> >
> > @@ -391,8 +400,8 @@ $ git show HEAD           # the tip of the current branch
> >  $ git show experimental      # the tip of the "experimental" branch
> >  -------------------------------------
> >
> > -Every commit has at least one "parent" commit, which points to the
> > -previous state of the project:
> > +Every commit has at least one "parent" commit (except the first),
> > +which points to the previous state of the project:
>
> And how can it have more than one parent? If you mention it, better come
> clean about merges (can be explained in detail later).

I have not mentined it, I've just added the exception that the
firt/root commits have zero parents.

>
> >  -------------------------------------
> >  $ git show HEAD^  # to see the parent of HEAD
>
> And if there are several parents?

Already explained before.

>
> > @@ -510,10 +519,10 @@ of the file:
> >  $ git diff v2.5:Makefile HEAD:Makefile.in
> >  -------------------------------------
>
> HEAD:Makefile.in doesn't need HEAD.

Not needed if the Makefile.in in the working directory is equal to the
file in HEAD.
But better explain new things.

Santi

Re: [PATCH] Documentation/tutorial: misc updates

[Junio C Hamano]

"Santi Béjar" <sbejar@gmail.com> writes:

> On 1/3/07, Horst H. von Brand <vonbrand@inf.utfsm.cl> wrote:
>> Santi Béjar <sbejar@gmail.com> wrote:
>> >
>> > -Every commit has at least one "parent" commit, which points to the
>> > -previous state of the project:
>> > +Every commit has at least one "parent" commit (except the first),
>> > +which points to the previous state of the project:
>>
>> And how can it have more than one parent? If you mention it, better come
>> clean about merges (can be explained in detail later).
>
> I have not mentined it, I've just added the exception that the
> firt/root commits have zero parents.

Well, it does not matter who originally is at fault ;-).

Let's just do this.

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index f0a5526..0cc234f 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -400,7 +400,7 @@ $ git show HEAD		# the tip of the current branch
 $ git show experimental	# the tip of the "experimental" branch
 -------------------------------------
 
-Every commit has at least one "parent" commit (except the first),
+Every commit usually has one "parent" commit
 which points to the previous state of the project:
 
 -------------------------------------

After this paragraph, we say "merge has more than one", so it's
all consistent and presented in the right order.  By the time
the reader starts wondering about the initial commit, we've
shown the use of HEAD^^^^ and HEAD~$n enough that the reader can
experiment on his/her own.

Re: [PATCH] Documentation/tutorial: misc updates

[Santi Béjar]

On 1/3/07, Junio C Hamano <junkio@cox.net> wrote:
> "Santi Béjar" <sbejar@gmail.com> writes:
>
> > On 1/3/07, Horst H. von Brand <vonbrand@inf.utfsm.cl> wrote:
> >> Santi Béjar <sbejar@gmail.com> wrote:
> >> >
> >> > -Every commit has at least one "parent" commit, which points to the
> >> > -previous state of the project:
> >> > +Every commit has at least one "parent" commit (except the first),
> >> > +which points to the previous state of the project:
> >>
> >> And how can it have more than one parent? If you mention it, better come
> >> clean about merges (can be explained in detail later).
> >
> > I have not mentined it, I've just added the exception that the
> > firt/root commits have zero parents.
>
> Well, it does not matter who originally is at fault ;-).

Sure, we all try to make git better and better.

>
> Let's just do this.
>
> diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
> index f0a5526..0cc234f 100644
> --- a/Documentation/tutorial.txt
> +++ b/Documentation/tutorial.txt
> @@ -400,7 +400,7 @@ $ git show HEAD             # the tip of the current branch
>  $ git show experimental        # the tip of the "experimental" branch
>  -------------------------------------
>
> -Every commit has at least one "parent" commit (except the first),
> +Every commit usually has one "parent" commit
>  which points to the previous state of the project:
>
>  -------------------------------------
>
> After this paragraph, we say "merge has more than one", so it's
> all consistent and presented in the right order.  By the time
> the reader starts wondering about the initial commit, we've
> shown the use of HEAD^^^^ and HEAD~$n enough that the reader can
> experiment on his/her own.

OK here.

Santi