[PATCH v2 0/3] Documentation/git-bundle.txt: promote --all for full backup

From: kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date: Oct 29, 2024, 20:41 UTC
Message-ID: <cover.1730234365.git.code@khaugsbakk.name>
In-Reply-To: <cover.1729451376.git.code@khaugsbakk.name>

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The documentation for git-bundle(1) now properly covers `--all`, the option from git-rev-list(1) that can be used to package all refs. A "Discussions" 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. The first thing I noticed was that `--all` wasn’t in the synopsis.

+Cc is just `./contrib/contacts/git-contacts` minus Junio. (Although he is inactive (from v1); keeping Cc on the series since it is customary)

Cheers

§ Changes in v2

• Patch v1 1/4: drop
• Patch v2 1/3: combine with previous paragraph and drop “mirror”
  sentence
• Patch v2 3/3: fix `make lint-docs` failure

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

 Documentation/git-bundle.txt | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

Interdiff against v1:

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index b5cc4746b45..7bffd2e4a05 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git bundle' create [-q | --quiet | --progress]
-		    [--version=<version>] <file> (<git-rev-list-args> | --all)
+		    [--version=<version>] <file> <git-rev-list-args>
 'git bundle' verify [-q | --quiet] <file>
 'git bundle' list-heads <file> [<refname>...]
 'git bundle' unbundle [--progress] <file> [<refname>...]
@@ -23,11 +23,8 @@ the "offline" transfer of Git objects without an active "server"
 sitting on the other side of the network connection.
 
 They can be used to create both incremental and full backups of a
-repository, and to relay the state of the references in one repository
-to another.
-
-You can use `git bundle create <file> --all` to create a full backup of
-your repository.
+repository (`git bundle create <file> --all`), and to relay the state of
+the references in one repository to another.
 
 Git commands that fetch or otherwise "read" via protocols such as
 `ssh://` and `https://` can also operate on bundle files. It is
@@ -206,8 +203,6 @@ It is okay to err on the side of caution, causing the bundle file
 to contain objects already in the destination, as these are ignored
 when unpacking at the destination.
 
-If you want to match `git clone --mirror`, which would include your
-refs such as `refs/remotes/*`, use `--all`.
 If you want to provide the same set of refs that a clone directly
 from the source repository would get, use `--branches --tags` for
 the `<git-rev-list-args>`.
@@ -335,7 +330,7 @@ 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[1], section "TRANSFERS" for a discussion of the
+See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
 problems associated with file syncing across systems.
 
 FILE FORMAT
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 6d610253575..127518c2a8d 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -17,7 +17,7 @@
 
 #define BUILTIN_BUNDLE_CREATE_USAGE \
 	N_("git bundle create [-q | --quiet | --progress]\n" \
-	   "                  [--version=<version>] <file> (<git-rev-list-args> | --all)")
+	   "                  [--version=<version>] <file> <git-rev-list-args>")
 #define BUILTIN_BUNDLE_VERIFY_USAGE \
 	N_("git bundle verify [-q | --quiet] <file>")
 #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
Range-diff against v1:
1:  39bdc5941c7 ! 1:  e9be866f33d Documentation/git-bundle.txt: mention --all in Synopsis
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    Documentation/git-bundle.txt: mention --all in Synopsis
    +    Documentation/git-bundle.txt: mention full backup example
     
    -    `--all` is convenient for bundling all refs.  But it is only mentioned
    -    once, halfway through the doc, under the demure section “Object
    -    prerequisites”.  It deserves to be mentioned as an alternative to
    -    `<git-rev-list-args>`.
    +    Tell the user how to make a full backup of the repository right at the
    +    start of the doc.
    +
    +    This is a requested use-case.[1]  But the doc is a bit unassuming
    +    about it:
    +
    +      “ If you want to match `git clone --mirror`, which would include your
    +        refs such as `refs/remotes/*`, use `--all`.
    +
    +    The user cannot be expected to formulate “I want a full backup” as “I
    +    want to match `git clone --mirror`” for a bundle file or something.
    +    Let’s drop this mention of `--all` later in the doc and frontload it.
    +
    +    † 1: E.g.:
    +
    +        • https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo
    +        • https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    -    Long line in bundle.c now?
    +    v2:
    +    • Mention as a parenthetical on an existing paragraph (don’t create a
    +      new sentence and paragraph)
    +    • Remove the “mirror” mention
    +
    +      Link (both): https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/
     
      ## Documentation/git-bundle.txt ##
    -@@ Documentation/git-bundle.txt: SYNOPSIS
    - --------
    - [verse]
    - 'git bundle' create [-q | --quiet | --progress]
    --		    [--version=<version>] <file> <git-rev-list-args>
    -+		    [--version=<version>] <file> (<git-rev-list-args> | --all)
    - 'git bundle' verify [-q | --quiet] <file>
    - 'git bundle' list-heads <file> [<refname>...]
    - 'git bundle' unbundle [--progress] <file> [<refname>...]
    -
    - ## builtin/bundle.c ##
    -@@
    +@@ Documentation/git-bundle.txt: the "offline" transfer of Git objects without an active "server"
    + sitting on the other side of the network connection.
    + 
    + They can be used to create both incremental and full backups of a
    +-repository, and to relay the state of the references in one repository
    +-to another.
    ++repository (`git bundle create <file> --all`), and to relay the state of
    ++the references in one repository to another.
    + 
    + Git commands that fetch or otherwise "read" via protocols such as
    + `ssh://` and `https://` can also operate on bundle files. It is
    +@@ Documentation/git-bundle.txt: It is okay to err on the side of caution, causing the bundle file
    + to contain objects already in the destination, as these are ignored
    + when unpacking at the destination.
      
    - #define BUILTIN_BUNDLE_CREATE_USAGE \
    - 	N_("git bundle create [-q | --quiet | --progress]\n" \
    --	   "                  [--version=<version>] <file> <git-rev-list-args>")
    -+	   "                  [--version=<version>] <file> (<git-rev-list-args> | --all)")
    - #define BUILTIN_BUNDLE_VERIFY_USAGE \
    - 	N_("git bundle verify [-q | --quiet] <file>")
    - #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
    +-If you want to match `git clone --mirror`, which would include your
    +-refs such as `refs/remotes/*`, use `--all`.
    + If you want to provide the same set of refs that a clone directly
    + from the source repository would get, use `--branches --tags` for
    + the `<git-rev-list-args>`.
2:  f7d9aa89c95 < -:  ----------- Documentation/git-bundle.txt: mention full backup example
3:  33980a47d13 = 2:  f18f8ca453d Documentation/git-bundle.txt: mention --all in spec. refs
4:  63a431537b7 ! 3:  c50f9d405f9 Documentation/git-bundle.txt: discuss naïve backups
    @@ Commit message
     
     
      ## Notes (series) ##
    +    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 ##
    @@ Documentation/git-bundle.txt: You can also see what references it offers:
     +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[1], section "TRANSFERS" for a discussion of the
    ++See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
     +problems associated with file syncing across systems.
     +
      FILE FORMAT

base-commit: 34b6ce9b30747131b6e781ff718a45328aa887d0

-- 
2.46.1.641.g54e7913fcb6