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

From: Francis Moreau <francis.moro@gmail.com>
Date: Dec 8, 2006, 09:03 UTC
Message-ID: <38b2ab8a0612080103h14387513ta53e71fe715441f4@mail.gmail.com>

Andy Parkins wrote:

Show 29 quoted lines

> 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):
	...