[v2,3/3] Documentation/git-bundle.txt: discuss naïve backups

Commit Message

Kristoffer Haugsbakk Oct. 29, 2024, 8:41 p.m. UTC

From: Kristoffer Haugsbakk <[e-mail]>

It might be naïve to think that those who need this education would end
up here in the first place.  But I think it’s good to mention this
high-level concept here on a command which provides a backup strategy.

Signed-off-by: Kristoffer Haugsbakk <[e-mail]>
---

Notes (series):
    v2:
    • Fix gitfaq(7) link
    
      Link: https://lore.kernel.org/git/[e-mail]/#t
    v1:
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

Comments

Junio C Hamano Nov. 2, 2024, 1:39 a.m. UTC | #1

[e-mail] writes:

> +A naive way to make a full backup of a repository is to use something to
> +the effect of `cp -a <repo> <destination>`.  This is discouraged since
> +the repository could be written to during the copy operation.  In turn
> +some files at `<destination>` could be corrupted.

There is nothing wrong in the above, but ...

> +This is why it is recommended to use Git tooling for making repository
> +backups, either with this command or with e.g. linkgit:git-clone[1].

... "git bundle create - --all" in (or "git clone --mirror" from) a
repository cannot be an equivalent to "cp -a" in a quiescent
repository.  You'd lose what is staged, you'd lose per repository
configuration, you'd lose hooks, you may be losing other things I am
not remembering.

IOW, those who uses what you call "a naive way" may be doing so with
a valid reason.

So the patch is not quite correct as-is, even though it is going in
the right direction.  It discourages apples and recommends oranges.

Let me think aloud to see if I can come up with an improvement.

    It is tempting to do "cp -a <repository> <elsewhere>" or "tar cf
    - <repository>" to take a snapshot of a repository, but unless
    the repository is quiescent, you will get an incomplete snapshot
    with inconsiistent state.  If all you care about is the state of
    the objects and the refs that point to objects, you can instead
    use "git clone --mirror <repo> <elsewhere>" or "git bundle
    create <bndl> --all" to take a consistent snapshot.

    Note that you will lose other local states of the repository,
    such as the contents of the index, working tree, per-repository
    configuration, hooks, etc.

or something like that, perhaps?

Patch

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index bce62bc8309..7bffd2e4a05 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -319,6 +319,20 @@  You can also see what references it offers:
 $ git ls-remote mybundle
 ----------------
 
+DISCUSSION
+----------
+
+A naive way to make a full backup of a repository is to use something to
+the effect of `cp -a <repo> <destination>`.  This is discouraged since
+the repository could be written to during the copy operation.  In turn
+some files at `<destination>` could be corrupted.
+
+This is why it is recommended to use Git tooling for making repository
+backups, either with this command or with e.g. linkgit:git-clone[1].
+
+See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
+problems associated with file syncing across systems.
+
 FILE FORMAT
 -----------