Remote branchs -- how can I check them out?

Remote branchs -- how can I check them out?

[João Paulo Melo de Sampaio]

Hello, people.

When I just cloned git using

    git clone git://git.kernel.org/pub/scm/git/git.git

and I type

    git branch

it shows me I have only the 'master' branch in my local repository

    * master

and when I type

    git branch -a

it shows that there's all these branches remotely

    * master
      remotes/origin/HEAD -> origin/master
      remotes/origin/html
      remotes/origin/maint
      remotes/origin/man
      remotes/origin/master
      remotes/origin/next
      remotes/origin/pu
      remotes/origin/todo

What do I have to do to be able to see what's in the 'maint', 'next'
and 'todo' branches, for example?

And by the way, what are those branches all about? Their names
suggests they are maintenance branches (where you keep backward
compatibility with an older version?), the next version of git (1.7.4
version?) and future features under implementation (the to-do list?).

Thank you for your time!

-- 
João Paulo Melo de Sampaio
Computer Engineering Student @ UFSCar
Website: http://www.jpmelos.com
Twitter: twitter.com/jpmelos (@jpmelos)

Re: Remote branchs -- how can I check them out?

[Konstantin Khomoutov]

On Sun, Jan 30, 2011 at 01:05:07PM -0200, João Paulo Melo de Sampaio wrote:

> When I just cloned git using
> 
>     git clone git://git.kernel.org/pub/scm/git/git.git
> 
> and I type
> 
>     git branch
> 
> it shows me I have only the 'master' branch in my local repository
> 
>     * master
> 
> and when I type
> 
>     git branch -a
> 
> it shows that there's all these branches remotely
> 
>     * master
>       remotes/origin/HEAD -> origin/master
>       remotes/origin/html
>       remotes/origin/maint
>       remotes/origin/man
>       remotes/origin/master
>       remotes/origin/next
>       remotes/origin/pu
>       remotes/origin/todo
> 
> What do I have to do to be able to see what's in the 'maint', 'next'
> and 'todo' branches, for example?
These branches are local to your repository. They are "remote" in the
sense you're not supposed to modify them directly.
So to inspect such a branch just use its full name ("origin/next" for
instance) when working with commands like git-log.

See [1], [2] for more info.

Also your question appears to be quite basic which hints at that you did
not read a good book on Git before using it.  So starting at [3] is
recommended -- it mentions a bunch of good books and manuals (some of
which are available freely).

1. http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#examining-remote-branches
2. http://progit.org/book/ch3-5.html
3. http://git-scm.com/documentation

[RFC/PATCH 0/2] Re: Remote branchs -- how can I check them out?

[Jonathan Nieder]

Konstantin Khomoutov wrote:

> These branches are local to your repository. They are "remote" in the
> sense you're not supposed to modify them directly.
> So to inspect such a branch just use its full name ("origin/next" for
> instance) when working with commands like git-log.
>
> See [1], [2] for more info.
>
> Also your question appears to be quite basic which hints at that you did
> not read a good book on Git before using it.  So starting at [3] is
> recommended -- it mentions a bunch of good books and manuals

Pointing to good references is a valuable thing --- thank you for that.
But I also want to point out that if you need to read a book before Git
becomes usable then we are doing something wrong. :)

In this example, perhaps the "git branch" manual page needs some
improvement?

Jonathan Nieder (2):
  Documentation/branch: split description into subsections
  Documentation/branch: briefly explain what a branch is

 Documentation/git-branch.txt |   62 +++++++++++++++++++++++++-----------------
 1 files changed, 37 insertions(+), 25 deletions(-)

[PATCH 1/2] Documentation/branch: split description into subsections

[Jonathan Nieder]

Add headings for each form of the "git branch" command.  Hopefully
this will make the description easier to read straight through without
getting lost and help technical writers to see what needs improvement
in the treatment of each form.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   53 +++++++++++++++++++++++------------------
 1 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 9106d38..d3eeb94 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -18,25 +18,30 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-With no arguments, existing branches are listed and the current branch will
-be highlighted with an asterisk.  Option `-r` causes the remote-tracking
-branches to be listed, and option `-a` shows both.
+'git branch' [-r | -a]::
+	With no arguments, existing branches are listed and the current
+	branch will be highlighted with an asterisk.
+	Option `-r` causes the remote-tracking branches to be listed,
+	and option `-a` shows both.
 
-With `--contains`, shows only the branches that contain the named commit
-(in other words, the branches whose tip commits are descendants of the
-named commit).  With `--merged`, only branches merged into the named
-commit (i.e. the branches whose tip commits are reachable from the named
-commit) will be listed.  With `--no-merged` only branches not merged into
-the named commit will be listed.  If the <commit> argument is missing it
-defaults to 'HEAD' (i.e. the tip of the current branch).
-
-The command's second form creates a new branch head named <branchname>
-which points to the current 'HEAD', or <start-point> if given.
+'git branch' (--contains | --merged | --no-merged) [<commit>]::
+	With `--contains`, shows only the branches that contain the
+	named commit (in other words, the branches whose tip commits are
+	descendants of the named commit).  With `--merged`, only
+	branches merged into the named commit (i.e. the branches whose
+	tip commits are reachable from the named commit) will be listed.
+	With `--no-merged` only branches not merged into the named
+	commit will be listed.  If the <commit> argument is missing it
+	defaults to 'HEAD' (i.e.  the tip of the current branch).
 
+'git branch' <branchname> [<start-point>]::
+	The command's second form creates a new branch head named <branchname>
+	which points to the current 'HEAD', or <start-point> if given.
++
 Note that this will create the new branch, but it will not switch the
 working tree to it; use "git checkout <newbranch>" to switch to the
 new branch.
-
++
 When a local branch is started off a remote-tracking branch, git sets up the
 branch so that 'git pull' will appropriately merge from
 the remote-tracking branch. This behavior may be changed via the global
@@ -44,16 +49,18 @@ the remote-tracking branch. This behavior may be changed via the global
 overridden by using the `--track` and `--no-track` options, and
 changed later using `git branch --set-upstream`.
 
-With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
-If <oldbranch> had a corresponding reflog, it is renamed to match
-<newbranch>, and a reflog entry is created to remember the branch
-renaming. If <newbranch> exists, -M must be used to force the rename
-to happen.
-
-With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
-specify more than one branch for deletion.  If the branch currently
-has a reflog then the reflog will also be deleted.
+'git branch' (-m | -M) <oldbranch> <newbranch>::
+	With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
+	If <oldbranch> had a corresponding reflog, it is renamed to match
+	<newbranch>, and a reflog entry is created to remember the branch
+	renaming. If <newbranch> exists, -M must be used to force the rename
+	to happen.
 
+'git branch' (-d | -D) <branchname>::
+	With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
+	specify more than one branch for deletion.  If the branch currently
+	has a reflog then the reflog will also be deleted.
++
 Use -r together with -d to delete remote-tracking branches. Note, that it
 only makes sense to delete remote-tracking branches if they no longer exist
 in the remote repository or if 'git fetch' was configured not to fetch
-- 
1.7.4.rc3

Re: [PATCH 1/2] Documentation/branch: split description into subsections

[Sverre Rabbelier]

Heya,

2011/1/30 Jonathan Nieder <jrnieder@gmail.com>:
> Add headings for each form of the "git branch" command.  Hopefully
> this will make the description easier to read straight through without
> getting lost and help technical writers to see what needs improvement
> in the treatment of each form.

I like it. Thought for the future: it would be nice if at a sprint or
such we can read through and fix the rest of the documentation in a
similar way.

-- 
Cheers,

Sverre Rabbelier

[PATCH 2/2] Documentation/branch: briefly explain what a branch is

[Jonathan Nieder]

The new reader might not know what git refs are, that history is a
graph, the distinction between local, remote-tracking, and remote
branches, or how to visualize what is going on.  After this change,
those things are still probably not evident but at least there is an
early reminder of some of it.

Also explain how to create a branch before explaining how to list
them.  Based roughly on the description of v0.99.1~53 (Add "git
branch" script, 2005-07-11).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   35 ++++++++++++++++++++---------------
 1 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d3eeb94..abad7ba 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -18,6 +18,26 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
+Branches are references to commit objects, representing the tip of a
+line of history.  The branch you are working on is referred to
+by HEAD and the corresponding reference is updated each time
+linkgit:git-commit[1] or linkgit:git-merge[1] makes a new commit.
+
+'git branch' <branchname> [<start-point>]::
+	Creates a new branch named `<branchname>`.
+	If a starting point is specified, that will be where the branch
+	is created; otherwise, the new branch points to the `HEAD` commit.
++
+This will create a new branch, but it does not switch the working tree
+to it.  Use "git checkout <newbranch>" to start working on the new branch.
+
+When a local branch is started off a remote-tracking branch, git sets up the
+branch so that 'git pull' will appropriately merge from
+the remote-tracking branch. This behavior may be changed via the global
+`branch.autosetupmerge` configuration flag. That setting can be
+overridden by using the `--track` and `--no-track` options, and
+changed later using `git branch --set-upstream`.
+
 'git branch' [-r | -a]::
 	With no arguments, existing branches are listed and the current
 	branch will be highlighted with an asterisk.
@@ -34,21 +54,6 @@ DESCRIPTION
 	commit will be listed.  If the <commit> argument is missing it
 	defaults to 'HEAD' (i.e.  the tip of the current branch).
 
-'git branch' <branchname> [<start-point>]::
-	The command's second form creates a new branch head named <branchname>
-	which points to the current 'HEAD', or <start-point> if given.
-+
-Note that this will create the new branch, but it will not switch the
-working tree to it; use "git checkout <newbranch>" to switch to the
-new branch.
-+
-When a local branch is started off a remote-tracking branch, git sets up the
-branch so that 'git pull' will appropriately merge from
-the remote-tracking branch. This behavior may be changed via the global
-`branch.autosetupmerge` configuration flag. That setting can be
-overridden by using the `--track` and `--no-track` options, and
-changed later using `git branch --set-upstream`.
-
 'git branch' (-m | -M) <oldbranch> <newbranch>::
 	With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
 	If <oldbranch> had a corresponding reflog, it is renamed to match
-- 
1.7.4.rc3

Re: [PATCH 2/2] Documentation/branch: briefly explain what a branch is

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> The new reader might not know what git refs are, that history is a
> graph, the distinction between local, remote-tracking, and remote
> branches, or how to visualize what is going on.  After this change,
> those things are still probably not evident but at least there is an
> early reminder of some of it.
>
> Also explain how to create a branch before explaining how to list
> them.  Based roughly on the description of v0.99.1~53 (Add "git
> branch" script, 2005-07-11).
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
>  Documentation/git-branch.txt |   35 ++++++++++++++++++++---------------
>  1 files changed, 20 insertions(+), 15 deletions(-)

I think these two are good readability changes.  Just a few nits though.

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index d3eeb94..abad7ba 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -18,6 +18,26 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
>  
> +Branches are references to commit objects, representing the tip of a
> +line of history.  The branch you are working on is referred to
> +by HEAD and the corresponding reference is updated each time
> +linkgit:git-commit[1] or linkgit:git-merge[1] makes a new commit.

I think "makes a new commit" is a somewhat misleading thing to say (think
"fast forward" or "rebase that makes more than one").  The important point
is "advances your history", isn't it?  How about...

	... reference is updated with various operations that advance your
	history, e.g. linkgit:git-commit[1], linkgit:git-pull[1], etc.

Obviously we do not want to be exhausitve, so I tried to reword the above
in a way that makes it explicit that we are not trying to be.

> +'git branch' <branchname> [<start-point>]::
> +	Creates a new branch named `<branchname>`.
> +	If a starting point is specified, that will be where the branch
> +	is created; otherwise, the new branch points to the `HEAD` commit.
> ++
> +This will create a new branch, but it does not switch the working tree
> +to it.  Use "git checkout <newbranch>" to start working on the new branch.

I do not think we define what _switch_ means to explain "it does not
switch the working tree to it" anywhere in the glossary.

The operation not only "does not switcfh the working tree", but also does
not do anything to HEAD.  You and I know that, but a new reader might not,
and especially after hearing that "branch ... is referred to by HEAD",
might get a wrong impression that branch creation may do something to HEAD.

Perhaps...

	This only creates a new branch; you are still on the same branch
	you were on before.  If you want to start working on the new
	branch, say "git checkout <newbranch>".

might be less confusing (we might also want to hint "checkout -b").

Thanks.

Re: [RFC/PATCH 0/2] Re: Remote branchs -- how can I check them out?

[João Paulo Melo de Sampaio]

Thank you for your help, Konstantin, Jakub and Jonathan!

When I asked that, I've only read http://gitref.org/ so I guess I
didn't quite have a good grasp on the concepts. Now I've read some of
Pro Git and I'm understanding the concepts much better. Thank you for
pointing me those references, they'll be of good use!

-- 
João Paulo Melo de Sampaio
Computer Engineering Student @ UFSCar
Website: http://www.jpmelos.com
Twitter: twitter.com/jpmelos (@jpmelos)

Re: Remote branchs -- how can I check them out?

[Jakub Narebski]

João Paulo Melo de Sampaio <jpmelos@gmail.com> writes:

> Hello, people.
> 
> When I just cloned git using
> 
>     git clone git://git.kernel.org/pub/scm/git/git.git
> 
> and I type
> 
>     git branch
> 
> it shows me I have only the 'master' branch in my local repository
> 
>     * master
> 
> and when I type
> 
>     git branch -a
> 
> it shows that there's all these branches remotely
> 
>     * master
>       remotes/origin/HEAD -> origin/master
>       remotes/origin/html
>       remotes/origin/maint
>       remotes/origin/man
>       remotes/origin/master
>       remotes/origin/next
>       remotes/origin/pu
>       remotes/origin/todo
> 
> What do I have to do to be able to see what's in the 'maint', 'next'
> and 'todo' branches, for example?

Those are so called "remote-tracking branches", i.e. refs which follow
branches in some remote repository.  For example 'remotes/origin/master'
follows branch 'master' in remote 'origin'.  By follow I mean here that
on "git fetch" (also "git pull" and "git remote update") these 
remote-tracking branches would get updated to their value at remote.
 
Now if you only want to check wah's in given branch (beside using
"git show <branch>", "git ls-tree <branch>", "git show <branch>:<file>")
you can use e.g.

  $ git checkout origin/next

to check out _state_ of remotr-tracking branch origin/next, landing
in so called "detached HEAD" state, or unnamed branch (no branch).


If you want to do some work based on given branch, you should create
new local branch based on remote-tracking one, e.g. via

  $ git checkout -b --track next origin/next

IIRC nowadays doiung simply

  $ git checkout -t next

should DWIM to do the same.

> And by the way, what are those branches all about? Their names
> suggests they are maintenance branches (where you keep backward
> compatibility with an older version?), the next version of git (1.7.4
> version?) and future features under implementation (the to-do list?).

It is described in "Notes from maintainer" which you can find in git
mailing list archives, in 'todo' branch of git repository, and on Git
Wiki.


* 'master' - stable development, new major version is cut from it
* 'next' - development branch, not everything that makes it here
           would be in next version.  Rewound on new major version.
* 'maint' - maintenance branch for last version, minor revisions are
            cut from this; only bugfixes, no new development
* 'pu' - proposed updates, merge of interesting topic branches,
         very unstable, used to review proposed features

* 'todo' - not wery well maintained TODO list, som scripts used e.g.
           to send "What's cooking..." emails to git mailing list
* 'html', 'man' - compiled documentation

todo, html and man are detached branches.

HTH
-- 
Jakub Narebski
Poland
ShadeHawk on #git