From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
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@xxxxxxxxxxxxxxx>
## 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@xxxxxxxxxxxxxxx>
## 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
