[PATCH] Documentation: do not advertise --all in git-pull(1)

[PATCH] Documentation: do not advertise --all in git-pull(1)

[Thomas Rast]

Since 9c4a036 (Teach the --all option to 'git fetch', 2009-11-09), we
document git-fetch's option --all in fetch-options.txt.  However, that
file is also included by git-pull.txt, where the option makes no
sense.

Wrap the option with ifdef so that it does not appear on the git-pull
manpage.

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

Zing <zing@fastmail.fm> wrote:
> In 1.6.6, if I do:
> 
> $ git pull --all
> Fetching origin
> Fetching gnome
> You asked to pull from the remote '--all', but did not specify
> a branch. Because this is not the default configured remote
> for your current branch, you must specify a branch on the command line.

This one fixes the documentation problem, but I think there's a deeper
misunderstanding.  What did you hope to do with 'git pull --all'?  I
suspect most people on this list would take it to mean "fetch all
branches from all remotes, and merge them into HEAD".  I cannot
imagine a use-case where that would make any sense.  (And it wouldn't
work, because the current implementation of 'git fetch --all' leaves
only the last remote's branches in FETCH_HEAD.)

>From earlier discussions on the non-intuitiveness of git-pull, I kind
of suspect you wanted to fetch all remotes, and then "update" all
local branches that track some remote with their corresponding
remote-tracking branches.  In which case the question is: why do you
use local branches if you have them "blindly" track the upstream?


 Documentation/fetch-options.txt |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index ab6419f..6271615 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -1,5 +1,7 @@
+ifndef::git-pull[]
 --all::
 	Fetch all remotes.
+endif::git-pull[]
 
 -a::
 --append::
-- 
1.6.6.202.gdf32a

Re: [PATCH] Documentation: do not advertise --all in git-pull(1)

[Zing]

On Thu, 07 Jan 2010 17:09:33 +0100, Thomas Rast wrote:

> This one fixes the documentation problem, but I think there's a deeper
> misunderstanding.  What did you hope to do with 'git pull --all'?  I
> suspect most people on this list would take it to mean "fetch all
> branches from all remotes, and merge them into HEAD".  I cannot imagine
> a use-case where that would make any sense.  (And it wouldn't work,
> because the current implementation of 'git fetch --all' leaves only the
> last remote's branches in FETCH_HEAD.)
> 
> From earlier discussions on the non-intuitiveness of git-pull, I kind of
> suspect you wanted to fetch all remotes, and then "update" all local
> branches that track some remote with their corresponding remote-tracking
> branches.  In which case the question is: why do you use local branches
> if you have them "blindly" track the upstream?

Let me just state first that I'm a casual git user and I would have 
missed those earlier discussions.... sorry if this old news:

I do basically just use git to just "blindly" track upstream repos/
projects using local branches.  I realize this is "dumb" in a sense,
because it's basically just a copy of the remote branch that needs to be
fast-forwarded all the time; but it's just a handy lazy way for me to
remember which remote branches I want to "watch" with just a 'git branch' 
command, plus it's easier and shorter to just type the local branch names 
I specify than to type for example "origin/something" or "myotherremote/
something".

What I thought 'git pull --all' would do is just pass down the --all flag 
to fetch and that's it:

1. do a 'git fetch --all'
2. then do a 'git merge <tracked remote branch of the current local 
branch>', basically, in my case, just fast-forwarding my current local 
branch if need be.

I didn't think that 'git pull --all' would "update" all local branches 
that needed to be fast-forwarded.  It would be too, how to say, "messy" 
in the output, and not really what 'git pull' alone was doing before.  I 
did think it could be a possibility, so, really, I was trying it out to 
see what would happen.

The other possibility you mentioned about fetching all branches and then 
merging all of them to HEAD, didn't occur to me at all.  I can see now 
how it could make more intuitive sense from the perspective of a more 
"experienced" git person.  Personally, I don't think I'd ever need 
something like that.  HTH.