From: "Alain Kalker" <a.c.kal...@gmail.com>
Sent: Sunday, February 17, 2013 7:28 PM
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?)
Perhaps if you draft up a documentation patch that would fit in the
Examples section it could be discussed. The Example section allows that
the various caveats can stated and be covered.
It would also be worth linking to 'git rev-parse' under the
<git-rev-list-args> so folk would actually look it up.
It may be that the example(s) needs to include
--branches[=pattern]
--tags[=pattern]
rather than --all. to cover Junio's points.
The --all 'question/solution' has come up a number of times so it does
look worth having something in the documentation. This would be
something ;-)
Any comments or suggestions (including HHGTTG references!) are very
welcome.
-Alain
Do use Reply-All - include any Cc's in replies.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
