Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example

kristofferhaugsbakk@fastmail.com writes:

Contrasting (1) taking a backup and (2) extracting a backup later is a very useful way to frame the problem, but then, I'd say

 1. taking a backup, either full or incremental, of a repository

 2. using the backup, either full or incremental, to transfer the
    history of the origin repository to any repository (including
    itself) without needing any other connection between the two
    repositories.

Whether a full or an incremental, the resulting bundle file can be used as an offline medium and then later extracted elsewhere, even if there is no direct network connection between the origin repository and the destination repository. But you can extract in the origin repository as well.

But that would require a bit more surgery to the presentation order of the text, so I do not mind deferrring it to a later and separate series. If we were to go that route, it would be helpful to have a paragraph to describe how you use your "full backup" bundle to recover lost data from, though. To those of us who know what is happening, there is not much difference between the extraction side of the sneaker-net example, but as we framed the use in two distinct cases, it would be helpful to make each case stand on its own.

Are you sure the "except" part is factually correct?

I did

    $ git bundle create x.bndl --all && git ls-remote x.bndl |
      grep stash

and I see refs/stash listed there just fine. You should be able to extract them all with

    $ git clone --mirror x.bndl xxx && cd xxx && git for-each-ref |
      grep stash

and see that refs/stash gets propagated.

Fix is a simple s/except/including/ ;-)

And to make each case stand on its own, we would want to teach readers how to use the full backup to recover data from here, before moving on to the "next example".

    You can use the resulting bundle file as if it is a repository,
    a snapshot of it at the time the bundle was created.  You can
    use

    ---
    $ git ls-remote full.bndl
    ---

    to inspect what refs are recorded in it, and you can fetch from or
    even merge a branch out of it, with commands like:

    ---
    $ git fetch full.bndl my-butchered-topic
    $ git show-branch my-butchered-topic FETCH_HEAD
    $ git branch -f my-butchered-topic FETCH_HEAD
    $ git pull full.bndl  my-butchered-topic
    ---

    after you screwed up one of your branches and resurrect it from
    the backup.

or something like that.