diff mbox series

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

Message ID c8d5e3ee5040fbc5eaf89b6d22a8402613aac660.1731768344.git.code@khaugsbakk.name (mailing list archive)
State Accepted
Commit 820fd1a5694b8d96609590163088d3f14731b565
Headers show
Series [v4,1/4] Documentation/git-bundle.txt: mention full backup example | expand

Commit Message

Kristoffer Haugsbakk Nov. 16, 2024, 2:54 p.m. UTC 
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---

Notes (series):
    v4:
    • Mention the stash (knock-on effect from patch 1/4)
    v3:
    • Use `cp -r` instead of `cp -a` since the former is more widely
      supported (even though it is just an example)
    • Mention what this “full backup” does not cover here as well (see first
      patch)
    v2:
    • Fix gitfaq(7) link
    
      Link: https://lore.kernel.org/git/ZxfhAAgNlbEq60VB@nand.local/#t
    v1:
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
diff mbox series

Patch

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index eaa16fc4b83..504b8a8143a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -344,6 +344,24 @@  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 -r <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].
+But keep in mind that these tools will not help you backup state other
+than refs and commits.  In other words they will not help you backup
+contents of the index, working tree, the stash, per-repository
+configuration, hooks, etc.
+
+See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
+problems associated with file syncing across systems.
+
 FILE FORMAT
 -----------