Git bundles for backup and cloning: the Zaphod Beeblebrox thread

[Alain Kalker <a.c.kalker@gmail.com>]

>From the current documentation for git-bundle(1), it may not be clear for 
users unfamilliar with Git, how to create a bundle which can be used for 
backup purposes, or, more generally, to clone to a completely new 
repository.

Philip Oakley has posted a documentation patch some time ago, but Junio 
has pointed out several concerns.
Ref: http://thread.gmane.org/gmane.comp.version-control.git/205887/
focus=205897

Here's my attempt to summarize the concerns, adding some of my own, and a 
possible solution.

1. "Missing HEAD syndrome"
$ git bundle create <bundle> master
-or-
$ git bundle create <bundle> <branchname...>
-or-
$ git bundle create <bundle> --branches
-then-
$ git clone <bundle> <dir>

will be unable to checkout any files due to a missing ref for HEAD. 
Though this can be fixed by going into <dir> and doing `git checkout 
<ref>`, this is not very user-friendly.

2. "Detached HEAD syndrome"
$ git bundle create <bundle> HEAD
$ git clone <bundle> <dir>
will checkout files alright, but leaves one in a "detached HEAD" state.
 
3. "Exploding HEAD syndrome"
$ git bundle create <bundle> --all
will add the HEAD, but will add refs from refs/remotes/* too, which is 
not desirable when cloning, unless one sets up all the remotes (e.g. by 
restoring .git/config) as well.

Finally, my solution for backing up only the local branches of a 
repository:
$ git bundle create <bundle> --branches HEAD
but this may not be very easy for new users to figure out on their own 
unless well documented (perhaps a new flag?)

Any comments or suggestions (including HHGTTG references!) are very 
welcome.

-Alain