git-{fetch,pull} default behaviours (was Re: [PATCH] Explicitly add the default "git pull" behaviour to .git/config on clone)

["Francis Moreau" <francis.moro@gmail.com>]

Andy Parkins wrote:
> Without any specification in the .git/config file, git-pull will execute
> "git-pull origin"; which in turn defaults to pull from the first "pull"
> definition for the remote, "origin".
>
> This is a difficult set of defaults to track for a new user, and it's
> difficult to see what tells git to do this (especially when it is
> actually hard-coded behaviour).  To ameliorate this slightly, this patch
> explicitly specifies the default behaviour during a clone using the
> "branch" section of the config.
>
> For example, a clone of a typical repository would create a .git/config
> containing:
>   [remote "origin"]
>   url = proto://host/repo.git
>   fetch = refs/heads/master:refs/remotes/origin/master
>   [branch "master"]
>   remote = origin
>   merge = refs/heads/master
>
> The [branch "master"] section is such that there is no change to the
> functionality of git-pull, but that functionality is now explicitly
> documented.
>
> Signed-off-by: Andy Parkins <andyparkins@gmail.com>
> ---
> This is really to help newbies.  By explicitly documenting the default
> behaviour, it makes it clearer what is going on.  It also means no routing
> through documentation to find out what config option needs changing.
>

Well I would say that if you want newbies (like me) to understand
git-pull and git-fetch default behaviour, we should first fix their
documentations. I dunno if it's me but I really find it terrible to
read. A lot information are spread all across the doc and I haven't
found a logical organisation in it.

Just reading the synopsis of these two command at first glance does
not give a good view of the commands:

	git-fetch <options> <repository> <refspec> ...

For example, it doesn't say that all arguments are optional at first
look, does it ? How does it say that I can run 'git-fetch origin' ?

When reading git-fetch doc, you find some specific git-pull
documentation which is confusing. The same is true when reading
git-pull doc. Why not removing all remote stuffs from git-pull doc and
just give a link to git-fetch for example ? Why not stopping using
git-pull word in git-fetch doc ?

I'm not sure that putting the default behaviour documentation in git's
config file will help the very newbie that I am. I expect to understand
how a command works in its documentation not by reading some git's
internal config file. And my first feeling when reading them is "whoa
this command seems really complex to use..."

However maybe explaining the default behaviour by giving some examples
would make things much more easier to understand. For example

Examples
--------
	Running 'git-fetch' (without any arguments):
	This is equivalent to run "git-fetch origin"....

	Running 'git-fetch <repository>':
	...

	Running 'git-fetch <repository> <refspec>':
	....

	Running 'git-fetch <refspec>' (if possible):
	...

--