Documentation/git-bundle.txt: promote --all for full backup

From: Kristoffer Haugsbakk <[email protected]>

The documentation for git-bundle(1) now prominently covers --all, the option from git-rev-list(1) that can be used to package all refs. A "Discussion" section has also been added to address the naive backup strategy of copying a Git repository manually with cp(1) or some other non-Git tool.

---

The part above was for the-topic-summary.

I was prompted by SO questions like this one:

    https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo

I then compared VonC’s answer to the man page.

Cheers

§ Changes in v4

• Tell how to recover the backup (patch 1/4)
• Fix confusion regarding refs/stash (patches 1/4 and 4/4)

Kristoffer Haugsbakk (4):
Documentation/git-bundle.txt: mention full backup example Documentation/git-bundle.txt: remove old --all example Documentation/git-bundle.txt: mention --all in spec. refs Documentation/git-bundle.txt: discuss naïve backups

 Documentation/git-bundle.txt | 59 ++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 9 deletions(-)

Interdiff against v3:

index ad9ab3247f5..504b8a8143a 100644
@@ -216,21 +216,28 @@ EXAMPLES
 We'll discuss two cases:
 
 1. Taking a full backup of a repository
-2. Transfer the history of a repository to another machine when the two
-   machines have no direct connection
+2. Transferring the history of a repository to another machine when the
+   two machines have no direct connection
 
 First let's consider a full backup of the repository.  The following
 command will take a full backup of the repository in the sense that all
-refs are included in the bundle (except `refs/stash`, i.e. the stash):
+refs are included in the bundle:
 
 ----------------
-$ git bundle create <file> --all
+$ git bundle create backup.bundle --all
 ----------------
 
 But note again that this is only for the refs, i.e. you will only
 include refs and commits reachable from those refs.  You will not
 include other local state, such as the contents of the index, working
-tree, per-repository configuration, hooks, etc.
+tree, the stash, per-repository configuration, hooks, etc.
+
+You can later recover that repository by using for example
+linkgit:git-clone[1]:
+
+----------------
+$ git clone backup.bundle <new directory>
+----------------
 
 For the next example, assume you want to transfer the history from a
 repository R1 on machine A to another repository R2 on machine B.

@@ -349,8 +356,8 @@ 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, per-repository configuration,
-hooks, etc.
+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.

Range-diff against v3:
1: b222c6787a7 ! 1: 5121edfee67 Documentation/git-bundle.txt: mention full backup example
@@ Commit message

## Notes (series) ##
+ v4:
+ • Drop the part about refs/stash since that is wrong. What we want to
+ communicate is that the state of the stash is not transferred since
+ git-clone(1) does not include the reflogs. We can just lump that in
+ with the existin list of the index, working tree, … etc.
+
+ Link: https://lore.kernel.org/git/[email protected]/
+ • Add para. describing how to recover the backup
+
+ Link: https://lore.kernel.org/git/[email protected]/
+ • Correct tense: “transferring”
v3:
• Elaborate on “full backups” in Examples instead
• Just point to the section in the second paragraph where everything is
@@ Documentation/git-bundle.txt: bundle.
+We'll discuss two cases:
+
+1. Taking a full backup of a repository
-+2. Transfer the history of a repository to another machine when the two
-+ machines have no direct connection
++2. Transferring the history of a repository to another machine when the
++ two machines have no direct connection
+
+First let's consider a full backup of the repository. The following +command will take a full backup of the repository in the sense that all
-+refs are included in the bundle (except refs/stash, i.e. the stash):
++refs are included in the bundle:
+
+----------------
-+$ git bundle create <file> --all
++$ git bundle create backup.bundle --all
+----------------
+
+But note again that this is only for the refs, i.e. you will only +include refs and commits reachable from those refs. You will not +include other local state, such as the contents of the index, working
-+tree, per-repository configuration, hooks, etc.
++tree, the stash, per-repository configuration, hooks, etc.
++
++You can later recover that repository by using for example ++linkgit:git-clone[1]:
++
++----------------
++$ git clone backup.bundle <new directory>
++----------------
+
+For the next example, assume you want to transfer the history from a +repository R1 on machine A to another repository R2 on machine B.

2:  f0dbe356ca6 = 2:  7e9f320fade Documentation/git-bundle.txt: remove old `--all` example
3:  8336b0f451e = 3:  4e9907f092e Documentation/git-bundle.txt: mention --all in spec. refs
4:  0ab05a4cf09 ! 4:  c8d5e3ee504 Documentation/git-bundle.txt: discuss naïve backups

@@ Commit message

## 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)
@@ Documentation/git-bundle.txt: You can also see what references it offers:
+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, per-repository configuration, -+hooks, etc.
++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.

base-commit: 34b6ce9b30747131b6e781ff718a45328aa887d0

2.47.0