need advice on usage patterns

need advice on usage patterns

[Geoff Russell]

Hi,

I'm after advice on usage patterns.

We are looking to use git to manage our release+patching process.  We
release our
software as a couple of directories (bin+tables).  Mostly we then send updates
to single customers without always testing that the update will work
for all customers.
Other updates apply to everybody.

Our thought is to have a "central" repository with the well tested
programs and branches for
each customer for versions that should not be sent to everybody.  The
developers work on their
own local repositories and push branches to the central one for final
testing prior to distribution.
The most common usage would be to rebase the branches on the latest master.
A developer should be able to just "git pull" and get updates to
branches for all customers.

There are notes on the "git pull" man page about not working on a remote branch
but having a local branch with a different name and merging the remote branch.
Why is this necessary?

Does anyone have comments or advice on alternative ways to manage
this? The remote branch
commands seem rather complex, has anybody written scripts to
simplify the process of interacting with remote branches?

Cheers and thanks,

Geoff Russell

git pull (Re: need advice on usage patterns)

[Jonathan Nieder]

Hi Geoff,

Geoff Russell wrote:

> There are notes on the "git pull" man page about not working on a remote branch
> but having a local branch with a different name and merging the remote branch.
> Why is this necessary?

The "git pull" man page is very unclear, I agree.  Especially when
starting out, I would recommend looking at the User’s Manual (and the
other resources the git(1) man page recommends).

In this case, the section to look at would be Chapter 4, on Sharing
development with others[1].

Thanks for noticing.
Jonathan

[1] http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#sharing-development

-- 8< --
Subject: pull documentation: Flesh out description

The current description in the pull man page does not say much more
than that “git pull” is fetch + merge.  Though that is all a person
needs to know in the end, it would be useful to summarize a bit about
what those commands do for new readers.

Most of this description is taken from the “git merge” docs.

Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-pull.txt |   61 +++++++++++++++++++++++++++++++++++--------
 1 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10..8803680 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,66 @@ git-pull - Fetch from and merge with another repository or a local branch
 
 SYNOPSIS
 --------
-'git pull' <options> <repository> <refspec>...
+'git pull' <options> <repository> <branch>...
 
 
 DESCRIPTION
 -----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
 
-Note that you can use `.` (current directory) as the
-<repository> to pull from the local repository -- this is useful
-when merging local branches into the current branch.
+Incorporates changes from a remote repository into the current
+branch.  In its default mode, a `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
 
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
-with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1].  <branch> can be an
+arbitrary refspec (for example, the name of a tag), but
+usually it is the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C master on origin
+         /
+    D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `master` (i.e., `E`)
+until its current commit (`C`) on top of `master` and record the
+result in a new commit along with the names of the two parent commits
+and a log message from the user describing the changes.
+
+------------
+          A---B---C remotes/origin/master
+         /         \
+    D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.  To cancel a conflicting merge,
+use `git reset --merge`.
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
 
 OPTIONS
 -------
 
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
-- 
1.7.1

Re: git pull (Re: need advice on usage patterns)

[Thomas Rast]

Jonathan Nieder wrote:
> +Incorporates changes from a remote repository into the current
> +branch.  In its default mode, a `git pull` is shorthand for
> +`git fetch` followed by `git merge FETCH_HEAD`.

In my ears, "a `git pull` is..." sounds weird.  I would remove the
'a'.  But maybe it's just my non-native English hard(ly) at work...

> -*Warning*: Running 'git pull' (actually, the underlying 'git merge')
> -with uncommitted changes is discouraged: while possible, it leaves you
> -in a state that is hard to back out of in the case of a conflict.
[...]
> +See linkgit:git-merge[1] for details, including how conflicts
> +are presented and handled.  To cancel a conflicting merge,
> +use `git reset --merge`.
> +
> +If any of the remote changes overlap with local uncommitted changes,
> +the merge will be automatically cancelled and the work tree untouched.
> +It is generally best to get any local changes in working order before
> +pulling or stash them away with linkgit:git-stash[1].

There's a slight risk with it because people might read this version
of the manpage online and then conclude that it is safe to try a merge
with uncommitted changes, only to find that their git-reset doesn't
support --merge yet.  Or worse, verify that their git-reset has
--merge by a quick test (1b5b465 is in 1.6.2) but then find that it
does not help with backing out of a merge (e11d7b5 is only in 1.7.0!).

Then again, who reads these manpages anyway?  And we shouldn't let old
versions get in the way of having consistent and up-to-date docs.  So,

Acked-by: Thomas Rast <trast@student.ethz.ch>

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: git pull (Re: need advice on usage patterns)

[Ævar Arnfjörð Bjarmason]

On Mon, Jul 26, 2010 at 03:36, Jonathan Nieder <jrnieder@gmail.com> wrote:

> -'git pull' <options> <repository> <refspec>...
> +'git pull' <options> <repository> <branch>...

Wasn't it "refspec" because git-pull can take args like
"refs/remotes/origin/*:refs/heads/*", not just branch names?

Re: git pull (Re: need advice on usage patterns)

[Geoff Russell]

On Mon, Jul 26, 2010 at 7:56 PM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> On Mon, Jul 26, 2010 at 03:36, Jonathan Nieder <jrnieder@gmail.com> wrote:
>
>> -'git pull' <options> <repository> <refspec>...
>> +'git pull' <options> <repository> <branch>...
>
> Wasn't it "refspec" because git-pull can take args like
> "refs/remotes/origin/*:refs/heads/*", not just branch names?
>

Yes.

Thinking about the pull as 2 operations "fetch+merge" should have
alerted me to the
possibility that it could update 2 branches, ... the one in the
<refspec> as well
as the current branch ... if they are different.

Thanks,

Geoff

Re: git pull (Re: need advice on usage patterns)

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:
> On Mon, Jul 26, 2010 at 03:36, Jonathan Nieder <jrnieder@gmail.com> wrote:

>> -'git pull' <options> <repository> <refspec>...
>> +'git pull' <options> <repository> <branch>...
>
> Wasn't it "refspec" because git-pull can take args like
> "refs/remotes/origin/*:refs/heads/*", not just branch names?

Yes, by abuse of language that might be called the noble lie (or
something; notice later where it says "<branch> can be an arbitrary
refspec).  Better ways to achieve the same effect would be welcome.

Re: git pull (Re: need advice on usage patterns)

[Jonathan Nieder]

Thomas Rast wrote:

> In my ears, "a `git pull` is..." sounds weird.  I would remove the
> 'a'.

Good idea.

> Jonathan Nieder wrote:

>> -*Warning*: Running 'git pull' (actually, the underlying 'git merge')
>> -with uncommitted changes is discouraged: while possible, it leaves you
>> -in a state that is hard to back out of in the case of a conflict.
>[...]
>> +See linkgit:git-merge[1] for details, including how conflicts
>> +are presented and handled.  To cancel a conflicting merge,
>> +use `git reset --merge`.
[...]
>                       Or worse, verify that their git-reset has
> --merge by a quick test (1b5b465 is in 1.6.2) but then find that it
> does not help with backing out of a merge (e11d7b5 is only in 1.7.0!).
> 
> Then again, who reads these manpages anyway?  And we shouldn't let old
> versions get in the way of having consistent and up-to-date docs.  So,

Agh, surely we can do better.  Maybe:

	See linkgit:git-merge[1] for details, including how conflicts
	are presented and handled.

	ifdef::stalenotes[]
	In git 1.7.0 or later, to cancel a conflicting merge, use
	`git reset --merge`.
	*Warning*: In older versions of git, running 'git pull'
	with uncommited changes is discouraged: while possible,
	it leaves you in a state that may be hard to back out of
	in the case of a conflict.
	else::stalenotes[]
	To cancel a conflicting merge, use `git reset --merge`.
	endif::stalenotes[]

with the appropriate corresponding change to todo:dodoc.sh.

Re: git pull (Re: need advice on usage patterns)

[Thomas Rast]

Jonathan Nieder wrote:
> Thomas Rast wrote:
> [...]
> >                       Or worse, verify that their git-reset has
> > --merge by a quick test (1b5b465 is in 1.6.2) but then find that it
> > does not help with backing out of a merge (e11d7b5 is only in 1.7.0!).
> > 
> > Then again, who reads these manpages anyway?  And we shouldn't let old
> > versions get in the way of having consistent and up-to-date docs.  So,
> 
> Agh, surely we can do better.  Maybe:
> 
> 	See linkgit:git-merge[1] for details, including how conflicts
> 	are presented and handled.
> 
> 	ifdef::stalenotes[]
> 	In git 1.7.0 or later, to cancel a conflicting merge, use
> 	`git reset --merge`.
> 	*Warning*: In older versions of git, running 'git pull'
> 	with uncommited changes is discouraged: while possible,
> 	it leaves you in a state that may be hard to back out of
> 	in the case of a conflict.
> 	else::stalenotes[]
> 	To cancel a conflicting merge, use `git reset --merge`.
> 	endif::stalenotes[]

Sounds good.  Maybe you can call this attribute 'webdocs' or so, so
that we have a generic means of modifying the kernel.org hosted docs?

Also, apparently there is no else::...[] so you have to do an
endif/ifndef pair.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch