Documentation/git-bundle.txt: promote --all for full backup
cover Documentation/git-bundle.txt: promote --all for full backup
From: Kristoffer Haugsbakk <[email protected]>
The documentation for git-bundle(1) now properly covers --all, the option 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.
---
The part above was for the-topic-summary.
And that about summarizes it.
Okay well. 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. Then one patch lead to another.
+Cc is just ./contrib/contacts/git-contacts minus Junio.
Cheers
Kristoffer Haugsbakk (4):
Documentation/git-bundle.txt: mention --all in Synopsis 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 | 21 +++++++++++++++++++-- builtin/bundle.c | 2 +- 2 files changed, 20 insertions(+), 3 deletions(-)
base-commit: 34b6ce9b30747131b6e781ff718a45328aa887d0
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH 1/4 Documentation/git-bundle.txt: mention --all in Synopsis
From: Kristoffer Haugsbakk <[email protected]>
--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>.
---
Notes (series):
Long line in bundle.c now?
Documentation/git-bundle.txt | 2 +- builtin/bundle.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/git-bundle.txt +1 -1
@@ -10,7 +10,7 @@ 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 +1 -1
@@ -17,7 +17,7 @@#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 \
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH 1/4] Documentation/git-bundle.txt: mention --all in Synopsis
Quoted 2 lines · On Sun, Oct 20, 2024, at 21:14, [email protected] wrote:
prerequisites”. It deserves to be mentioned as an alternative to
<git-rev-list-args>.
git-rev-list-args huh.
git-rev-lists(1) has --all. That must be were it comes from to begin with.
That’s why I kept looking for --all in all the wrong places.
This patch should be dropped.
Signature · 2 lines
Kristoffer Haugsbakk [email protected]
Re: [PATCH 1/4] Documentation/git-bundle.txt: mention --all in Synopsis
Quoted 4 lines · Kristoffer Haugsbakk
Quoted 2 lines · On Sun, Oct 20, 2024, at 21:14, [email protected] wrote:
prerequisites”. It deserves to be mentioned as an alternative to
<git-rev-list-args>.
Quoted 8 lines
git-rev-list-args huh.
git-rev-lists(1) has
--all. That must be were it comes from to begin with.That’s why I kept looking for
--allin all the wrong places.This patch should be dropped.
I was going to say... <git-rev-list-args> is a superset of {--all}. But dropping this makes sense.
Thanks,
Taylor
PATCH 2/4 Documentation/git-bundle.txt: mention full backup example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
🔗 1: https://stackoverflow.com/a/5578292/1725151
--- Documentation/git-bundle.txt | 3 +++ 1 file changed, 3 insertions(+)
Documentation/git-bundle.txt +3 -0
@@ -26,6 +26,9 @@ 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. + Git commands that fetch or otherwise "read" via protocols such as `ssh://` and `https://` can also operate on bundle files. It is possible linkgit:git-clone[1] a new repository from a bundle, to use
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH 2/4] Documentation/git-bundle.txt: mention full backup example
Quoted 8 lines · On Sun, Oct 20, 2024 at 09:15:00PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
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:
Quoted 7 lines
“ If you want to match
git clone --mirror, which would include yourrefs 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.
We do not typically use emoji characters in commit messages on the Git project. The convention here would be to write this as
[1]: https://stackoverflow.com/a/5578292/1725151
Quoted 10 lines
Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-bundle.txt | 3 +++ 1 file changed, 3 insertions(+)Documentation/git-bundle.txt +0
-0
Documentation/git-bundle.txt They can be used to create both incremental and full backups of a · line 31
Quoted 6 lines
Documentation/git-bundle.txt +3
-0@@ -26,6 +26,9 @@ 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. +
Looks good, and could likely be combined with the previous paragraph instead of breaking and starting a new one.
Now that you mention it here, does it make sense to drop the more subtle mention that you refer to in the patch message?
Thanks,
Taylor
Re: [PATCH 2/4] Documentation/git-bundle.txt: mention full backup example
Quoted 16 lines · Taylor Blau
Quoted 14 lines · On Sun, Oct 20, 2024 at 09:15:00PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
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 yourrefs 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.
Quoted 6 lines
Quoted 1 line
We do not typically use emoji characters in commit messages on the Git project. The convention here would be to write this as
[1]: https://stackoverflow.com/a/5578292/1725151
Ok. Will fix.
Quoted 9 lines
Documentation/git-bundle.txt They can be used to create both incremental and full backups of a · line 31
Quoted 3 lines
Documentation/git-bundle.txt +3
-0+You can use `git bundle create <file> --all` to create a full backup of +your repository. +Looks good, and could likely be combined with the previous paragraph instead of breaking and starting a new one.
Now that you mention it here, does it make sense to drop the more subtle mention that you refer to in the patch message?
Both sound good. I’ll see what it looks like when I sit down with it again.
Thanks
Signature · 2 lines
Kristoffer Haugsbakk [email protected]
PATCH 3/4 Documentation/git-bundle.txt: mention --all in spec. refs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Mention --all as an alternative in “Specifying References”.
--- Documentation/git-bundle.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-bundle.txt +1 -1
@@ -135,7 +135,7 @@ SPECIFYING REFERENCES --------------------- Revisions must be accompanied by reference names to be packaged in a -bundle. +bundle. Alternatively `--all` can be used to package all refs. More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH 3/4] Documentation/git-bundle.txt: mention --all in spec. refs
Quoted 8 lines · On Sun, Oct 20, 2024 at 09:15:01PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
Mention
--allas an alternative in “Specifying References”.Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-bundle.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Good.
Thanks,
Taylor
PATCH 4/4 Documentation/git-bundle.txt: discuss naïve backups
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
Notes (series):
Correct mention of the section? All-caps seems to be the convention.
Documentation/git-bundle.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
Documentation/git-bundle.txt +14 -0
@@ -324,6 +324,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[1], section "TRANSFERS" for a discussion of the +problems associated with file syncing across systems. + FILE FORMAT -----------
Signature · 1 line
2.46.1.641.g54e7913fcb6
Quoted 1 line · On Sun, Oct 20, 2024 at 09:14:58PM +0200, [email protected]…
+Cc is just
./contrib/contacts/git-contactsminus Junio.
Ævar, who you CC'd here is currently inactive[^1], so it may be unlikely that we receive a response from him.
Quoted 5 lines
Kristoffer Haugsbakk (4):
Documentation/git-bundle.txt: mention --all in SynopsisDocumentation/git-bundle.txt: mention full backup exampleDocumentation/git-bundle.txt: mention --all in spec. refsDocumentation/git-bundle.txt: discuss naïve backups
As you suggested elsewhere in the thread, I dropped the first patch from this series, but the other three look good. I had a small note on the second patch (first after dropping), but let me know if you plan to address it or not.
Thanks,
Taylor
[^1]: ...and missed. It would be nice to see you back sometime, Ævar.
Quoted 6 lines · On Sun, Oct 20, 2024 at 09:14:58PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
The documentation for git-bundle(1) now properly covers
--all, the option 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.
When applying to 'seen' last night, it looks like this topic caused some breakage here:
https://github.com/git/git/actions/runs/11449483611/job/31855169149#step:4:144
Would you mind taking a look, Kristoffer?
Thanks,
Taylor
Quoted 9 lines · Taylor Blau
Quoted 6 lines · On Sun, Oct 20, 2024 at 09:14:58PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
The documentation for git-bundle(1) now properly covers
--all, the option 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.
Quoted 7 lines
When applying to 'seen' last night, it looks like this topic caused some breakage here:
https://github.com/git/git/actions/runs/11449483611/job/31855169149#step:4:144
Would you mind taking a look, Kristoffer?
Ah, thanks for the heads up. I’ll take a look at it.
(’Tis a shame when we neglect to run five-second-run linters before sending out)
v2 cover Documentation/git-bundle.txt: promote --all for full backup
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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:
Documentation/git-bundle.txt +4 -9
@@ -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
builtin/bundle.c +1 -1
@@ -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 <[email protected]>
## 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
## 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/[email protected]/
## 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/[email protected]/#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
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH v2 1/3 Documentation/git-bundle.txt: mention full backup example
From: Kristoffer Haugsbakk <[email protected]>
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
---
Notes (series):
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/[email protected]/
Documentation/git-bundle.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
Documentation/git-bundle.txt +2 -4
@@ -23,8 +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. +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
@@ -203,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>`.
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH v2 1/3] Documentation/git-bundle.txt: mention full backup example
Quoted 10 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
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 yourrefs such as `refs/remotes/*`, use `--all`.
What's the open fancy quote followed by a SP doing there, apparently without the matching closing one? Can we replace it with a SP?
Quoted 9 lines
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--alllater in the doc and frontload it.Documentation/git-bundle.txt +0
-0
Documentation/git-bundle.txt the "offline" transfer of Git objects without an active "server" · line 27
Quoted 7 lines
Documentation/git-bundle.txt +2
-2@@ -23,8 +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. +repository (`git bundle create <file> --all`), and to relay the state of +the references in one repository to another.
In the new construction, it is unclear if the new command line example is about making a "full backup" and not "incremental", or it applies to both. I am not sure if this, especially with the removal of "--all" from the later section, is an improvement. Let me try if I can come up with a better version by elaborating the later section without touching this part.
This is not a new issue, but naïvely, one would expect "full backup" to allow one to recover lost .git/config entries. We should tighten the phrasing for "backups of a repository" to avoid such misleading false promises. As it is the primary motivation of this series to clarify how you would use the command for "full backup", I think this point is worth tackling as part of this series.
This also is not a new issue, but the dashed-option "--all" after "<file>" is an oddball from "git help cli"'s point of view. It perfectly fits within the SYNOPSIS for this command in that "--all" is merely a form of valid arguments you can give to "git rev-list", so I do not see anything that needs to be done on this point, though.
So, here is my attempt.
Documentation/git-bundle.txt | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-)
Documentation/git-bundle.txt +29 -10
@@ -22,9 +22,10 @@ Create, unpack, and manipulate "bundle" files. Bundles are used for 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. +They can be used to create both incremental and full backups of +objects and refs in a repository. They can be used to transfer the +state of the references to another repository, together with objects +these references point at. Git commands that fetch or otherwise "read" via protocols such as `ssh://` and `https://` can also operate on bundle files. It is
@@ -176,7 +177,7 @@ OBJECT PREREQUISITES When creating bundles it is possible to create a self-contained bundle that can be unbundled in a repository with no common history, as well as providing negative revisions to exclude objects needed in the -earlier parts of the history. +earlier parts of the history. This is like taking a "full backup". Feeding a revision such as `new` to `git bundle create` will create a bundle file that contains all the objects reachable from the revision
@@ -192,9 +193,11 @@ will require the revision `old` (and any objects reachable from it) to exist for the bundle to be "unbundle"-able: ---------------- -$ git bundle create full.bundle old..new +$ git bundle create incremental.bundle old..new ---------------- +Such a bundle file is like an "incremental backup". + A self-contained bundle without any prerequisites can be extracted into anywhere, even into an empty repository, or be cloned from (i.e., `new`, but not `old..new`).
@@ -203,11 +206,27 @@ 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>`. +If you want to prepare a bundle from which you can "git clone" as if +you were cloning from the repository, you can use `--branches +--tags` for the `<git-rev-list-args>`, as "git clone" transfers only +these two kinds of refs. + +If you use `--all` for the `<git-rev-list-args>`, the resulting +bundle will be able to recreate all the refs, including those +outside branches and tags, when extracted with "git clone --mirror". + +When creating an incremental bundle on top of an existing bundle, +`git bundle list-heads <existing-bundle>` can be used to extract +the then-current tips of the history recorded in it. Then you can +list them as the prerequisite objects when creating an incremental +bundle, e.g. + + $ git bundle create incremental.bundle --all --not \ + $(git bundle list-heads old.bundle | awk '{print $1}') + +which tells the command to include all refs (as if cloning with the +`--mirror` option), but without duplicating the objects already +available in the `old.bundle` bundle. The 'git bundle verify' command can be used to check whether your recipient repository has the required prerequisite commits for a
Re: [PATCH v2 1/3] Documentation/git-bundle.txt: mention full backup example
Quoted 7 lines · Junio C Hamano
Quoted 5 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Tell the user how to make a full backup of the repository right at the start of the doc.
Quoted 8 lines
Quoted 5 lines
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 yourrefs such as `refs/remotes/*`, use `--all`.What's the open fancy quote followed by a SP doing there, apparently without the matching closing one? Can we replace it with a SP?
I’ll replace it.
The idea came from merge commits like:
``` Pull more 9p reverts from Dominique Martinet: "Revert patches causing inode collision problems. The code simplification introduced significant regressions on servers that do not remap inode numbers when exporting multiple underlying filesystems with colliding inodes. See the top-most revert (commit be2ca3825372) for details. This problem had been ignored for too long and the reverts will also head to stable (6.9+). I'm confident this set of patches gets us back to previous behaviour (another related patch had already been reverted back in April and we're almost back to square 1, and the rest didn't touch inode lifecycle)" ```
But (1) space between the quote char and the text to make it stand out and (2) no trailing close quote (the deindent closes the quote).
Quoted 25 lines
Quoted 10 lines
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--alllater in the doc and frontload it.Documentation/git-bundle.txt +0
-0Documentation/git-bundle.txt the "offline" transfer of Git objects without an active "server" · line 27
Quoted 7 lines
Documentation/git-bundle.txt +2
-2@@ -23,8 +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. +repository (`git bundle create <file> --all`), and to relay the state of +the references in one repository to another.In the new construction, it is unclear if the new command line example is about making a "full backup" and not "incremental", or it applies to both. I am not sure if this, especially with the removal of "--all" from the later section, is an improvement. Let me try if I can come up with a better version by elaborating the later section without touching this part.
Quoted 6 lines
This is not a new issue, but naïvely, one would expect "full backup" to allow one to recover lost .git/config entries. We should tighten the phrasing for "backups of a repository" to avoid such misleading false promises. As it is the primary motivation of this series to clarify how you would use the command for "full backup", I think this point is worth tackling as part of this series.
Good point. The change is biased by the groove I’ve gotten into in the last years: (1) of never leaving unstaged changes for such a long time that I would be said if I lost them, and (2) never using git-stash(1) unless I’m popping the stack within the next fifteen seconds. So there is not much non-ref data (including the stash ref) that I would miss.
(But I have started using local repo config more so that could be lost)
And with worktrees, people could have a *quite a lot* of uncommitted state lying around. Since some people use worktrees like branches.
So yes. There is absolutely a need to make clear that this “full backup” doesn’t cover those things.
Quoted 10 lines
This also is not a new issue, but the dashed-option "--all" after "<file>" is an oddball from "git help cli"'s point of view. It perfectly fits within the SYNOPSIS for this command in that "--all" is merely a form of valid arguments you can give to "git rev-list", so I do not see anything that needs to be done on this point, though.
So, here is my attempt.
[…]
Thank you. I’ve adopted some of this for the next version.
Documentation/git-bundle.txt It is okay to err on the side of caution, causing the bundle file · line 229
Quoted 7 lines
Documentation/git-bundle.txt +7
-0+ + $ git bundle create incremental.bundle --all --not \ + $(git bundle list-heads old.bundle | awk '{print $1}') + +which tells the command to include all refs (as if cloning with the +`--mirror` option), but without duplicating the objects already +available in the `old.bundle` bundle.
This approach seems less manual than the incremental backup examples in the existing doc (Examples section). But I think I’ll stick to just the simple dump-to-file approach and leave the incremental backup example for the existing example.
Quoted 2 lines
The 'git bundle verify' command can be used to check whether your recipient repository has the required prerequisite commits for a
PATCH v2 2/3 Documentation/git-bundle.txt: mention --all in spec. refs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Mention --all as an alternative in “Specifying References”.
--- Documentation/git-bundle.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-bundle.txt +1 -1
@@ -132,7 +132,7 @@ SPECIFYING REFERENCES --------------------- Revisions must be accompanied by reference names to be packaged in a -bundle. +bundle. Alternatively `--all` can be used to package all refs. More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH v2 3/3 Documentation/git-bundle.txt: discuss naïve backups
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
Notes (series):
v2:
• Fix gitfaq(7) link
v1:
Correct mention of the section? All-caps seems to be the convention.
Documentation/git-bundle.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
Documentation/git-bundle.txt +14 -0
@@ -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 -----------
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH v2 3/3] Documentation/git-bundle.txt: discuss naïve backups
Documentation/git-bundle.txt You can also see what references it offers: · line 328
Quoted 4 lines · [email protected] writes:
Documentation/git-bundle.txt +4
-0+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 ...
Documentation/git-bundle.txt You can also see what references it offers: · line 331
Quoted 2 lines
Documentation/git-bundle.txt +2
-0+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?
Quoted 7 lines · On Tue, Oct 29, 2024 at 09:41:43PM +0100, [email protected]…
Kristoffer Haugsbakk (3):
Documentation/git-bundle.txt: mention full backup exampleDocumentation/git-bundle.txt: mention --all in spec. refsDocumentation/git-bundle.txt: discuss naïve backupsDocumentation/git-bundle.txt | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-)
This new version looks quite good to me, thanks for working on it! It would be nice to get some feedback from other reviewers on the list, but absent of that I think that this one is ready to start merging down.
Thanks,
Taylor
v3 cover Documentation/git-bundle.txt: promote --all for full backup
In reply to [email protected]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 v3
After some feedback from Junio I’ve added a disclaimer about what this “full backup” does not cover, like e.g. repo config. And since this requires some introduction and overall space (paragraphs), I’ve moved it into the Examples section. To structure this now two-example section it now starts with a list of what examples are coming up. The second example is marked by “For the next example”.
I’ve also noted what the “full backup” does not cover in the Discussion section.
The details are noted on the patches.
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 | 52 +++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 9 deletions(-)
Interdiff against v2:
Documentation/git-bundle.txt +29 -7
@@ -23,8 +23,9 @@ 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 (`git bundle create <file> --all`), and to relay the state of -the references in one repository to another. +repository (see the "full backup" example in "EXAMPLES"), and to relay +the state of the references in one repository to another (see the second +example). Git commands that fetch or otherwise "read" via protocols such as `ssh://` and `https://` can also operate on bundle files. It is
@@ -34,8 +35,6 @@ contained within it with linkgit:git-ls-remote[1]. There's no corresponding "write" support, i.e.a 'git push' into a bundle is not supported. -See the "EXAMPLES" section below for examples of how to use bundles. - BUNDLE FORMAT -------------
@@ -214,8 +213,27 @@ bundle. EXAMPLES -------- -Assume you want to transfer the history from a repository R1 on machine A -to another repository R2 on machine B. +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 + +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): + +---------------- +$ git bundle create <file> --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. + +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. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.
@@ -323,12 +341,16 @@ 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 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, 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 v2:
1: e9be866f33d ! 1: b222c6787a7 Documentation/git-bundle.txt: mention full backup example
@@ Metadata
## Commit message ##
Documentation/git-bundle.txt: mention full backup example
- Tell the user how to make a full backup of the repository right at the
- start of the doc.
+ Provide an example about how to make a “full backup” with caveats about
+ what that means in this case.
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
+ 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
@@ Commit message
• https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo
• https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo
+ Helped-by: Junio C Hamano <[email protected]>
## Notes (series) ##
+ v3:
+ • Elaborate on “full backups” in Examples instead
+ • Just point to the section in the second paragraph where everything is
+ elaborated
+ • Incorporate some of Junio’s suggestions:
+ • Mention what the “full backup” here does not include
+
+ Link: https://lore.kernel.org/git/[email protected]/
+ Link: https://lore.kernel.org/git/[email protected]/#t
+ • Remove the final paragraph pointing to Examples now that we mention it
+ in the second paragraph
v2:
• Mention as a parenthetical on an existing paragraph (don’t create a new sentence and paragraph)
@@ Notes (series)
Link (both): https://lore.kernel.org/git/[email protected]/
+
+ ## Notes (meta-trailers) ##
+ Helped-by: Junio C Hamano <[email protected]>
+ Link: https://lore.kernel.org/git/[email protected]/
+
## Documentation/git-bundle.txt ##
@@ Documentation/git-bundle.txt: the "offline" transfer of Git objects without an active "server"
sitting on the other side of the network connection.
@@ Documentation/git-bundle.txt: the "offline" transfer of Git objects without an a
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.
++repository (see the "full backup" example in "EXAMPLES"), and to relay
++the state of the references in one repository to another (see the second ++example).
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.
+@@ Documentation/git-bundle.txt: contained within it with linkgit:git-ls-remote[1]. There's no
+ corresponding "write" support, i.e.a 'git push' into a bundle is not
+ supported.
+
+-See the "EXAMPLES" section below for examples of how to use bundles.
+-
+ BUNDLE FORMAT
+ -------------
+
+@@ Documentation/git-bundle.txt: bundle.
+ EXAMPLES
+ --------
--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>.
+-Assume you want to transfer the history from a repository R1 on machine A +-to another repository R2 on machine B.
++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
++
++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):
++
++----------------
++$ git bundle create <file> --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.
++
++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.
+ For whatever reason, direct connection between A and B is not allowed,
+ but we can move data from A to B via some mechanism (CD, email, etc.).
+ We want to update R2 with development made on the branch master in R1.
-: ----------- > 2: f0dbe356ca6 Documentation/git-bundle.txt: remove old `--all` example 2: f18f8ca453d = 3: 8336b0f451e Documentation/git-bundle.txt: mention --all in spec. refs 3: c50f9d405f9 ! 4: 0ab05a4cf09 Documentation/git-bundle.txt: discuss naïve backups
@@ Commit message
## Notes (series) ##
+ 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
@@ Documentation/git-bundle.txt: You can also see what references it offers:
+----------
+
+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 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, 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
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH v3 1/4 Documentation/git-bundle.txt: mention full backup example
From: Kristoffer Haugsbakk <[email protected]>
Provide an example about how to make a “full backup” with caveats about what that means in this case.
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
---
Notes (series):
v3:
• Elaborate on “full backups” in Examples instead
• Just point to the section in the second paragraph where everything is elaborated
• Incorporate some of Junio’s suggestions:
• Mention what the “full backup” here does not include
• Remove the final paragraph pointing to Examples now that we mention it in the second paragraph
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/[email protected]/
Notes (meta-trailers):
Documentation/git-bundle.txt | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-)
Documentation/git-bundle.txt +24 -6
@@ -23,8 +23,9 @@ 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 (see the "full backup" example in "EXAMPLES"), and to relay +the state of the references in one repository to another (see the second +example). Git commands that fetch or otherwise "read" via protocols such as `ssh://` and `https://` can also operate on bundle files. It is
@@ -34,8 +35,6 @@ contained within it with linkgit:git-ls-remote[1]. There's no corresponding "write" support, i.e.a 'git push' into a bundle is not supported. -See the "EXAMPLES" section below for examples of how to use bundles. - BUNDLE FORMAT -------------
@@ -216,8 +215,27 @@ bundle. EXAMPLES -------- -Assume you want to transfer the history from a repository R1 on machine A -to another repository R2 on machine B. +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 + +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): + +---------------- +$ git bundle create <file> --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. + +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. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.
Signature · 1 line
2.46.1.641.g54e7913fcb6
Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example
Documentation/git-bundle.txt bundle. · line 222
Quoted 5 lines · [email protected] writes:
Documentation/git-bundle.txt +5
-0+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
Contrasting (1) taking a backup and (2) extracting a backup later is a very useful way to frame the problem, but then, I'd say
1. taking a backup, either full or incremental, of a repository
2. using the backup, either full or incremental, to transfer the history of the origin repository to any repository (including itself) without needing any other connection between the two repositories.
Whether a full or an incremental, the resulting bundle file can be used as an offline medium and then later extracted elsewhere, even if there is no direct network connection between the origin repository and the destination repository. But you can extract in the origin repository as well.
But that would require a bit more surgery to the presentation order of the text, so I do not mind deferrring it to a later and separate series. If we were to go that route, it would be helpful to have a paragraph to describe how you use your "full backup" bundle to recover lost data from, though. To those of us who know what is happening, there is not much difference between the extraction side of the sneaker-net example, but as we framed the use in two distinct cases, it would be helpful to make each case stand on its own.
Documentation/git-bundle.txt bundle. · line 226
Quoted 3 lines
Documentation/git-bundle.txt +3
-0+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):
Are you sure the "except" part is factually correct?
I did
$ git bundle create x.bndl --all && git ls-remote x.bndl |
grep stashand I see refs/stash listed there just fine. You should be able to extract them all with
$ git clone --mirror x.bndl xxx && cd xxx && git for-each-ref |
grep stashand see that refs/stash gets propagated.
Fix is a simple s/except/including/ ;-)
Documentation/git-bundle.txt bundle. · line 235
Quoted 8 lines
+----------------
+$ git bundle create <file> --all
+----------------Documentation/git-bundle.txt +5
-0+ +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.
And to make each case stand on its own, we would want to teach readers how to use the full backup to recover data from here, before moving on to the "next example".
You can use the resulting bundle file as if it is a repository, a snapshot of it at the time the bundle was created. You can use
---
$ git ls-remote full.bndl
---
to inspect what refs are recorded in it, and you can fetch from or even merge a branch out of it, with commands like:
---
$ git fetch full.bndl my-butchered-topic $ git show-branch my-butchered-topic FETCH_HEAD $ git branch -f my-butchered-topic FETCH_HEAD $ git pull full.bndl my-butchered-topic
---
after you screwed up one of your branches and resurrect it from the backup.
or something like that.
Quoted 5 lines
Documentation/git-bundle.txt +2
-0+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. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.
Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example
Quoted 24 lines · Junio C Hamano
Documentation/git-bundle.txt bundle. · line 222
Quoted 5 lines · [email protected] writes:
Documentation/git-bundle.txt +5
-0+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 connectionContrasting (1) taking a backup and (2) extracting a backup later is a very useful way to frame the problem, but then, I'd say
1. taking a backup, either full or incremental, of a repository
2. using the backup, either full or incremental, to transfer the history of the origin repository to any repository (including itself) without needing any other connection between the two repositories.
Whether a full or an incremental, the resulting bundle file can be used as an offline medium and then later extracted elsewhere, even if there is no direct network connection between the origin repository and the destination repository. But you can extract in the origin repository as well.
Quoted 8 lines
But that would require a bit more surgery to the presentation order of the text, so I do not mind deferrring it to a later and separate series. If we were to go that route, it would be helpful to have a paragraph to describe how you use your "full backup" bundle to recover lost data from, though. To those of us who know what is happening, there is not much difference between the extraction side of the sneaker-net example, but as we framed the use in two distinct cases, it would be helpful to make each case stand on its own.
Sure. I should be able to fit in a paragraph about using that backup bundle.
Quoted 5 lines
Documentation/git-bundle.txt bundle. · line 226
Quoted 3 lines
Documentation/git-bundle.txt +3
-0+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):Are you sure the "except" part is factually correct?
It was in my testing/to my recollection. Hmm but I must have managed to fool myself somehow. :P
Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example
Quoted 6 lines · Kristoffer Haugsbakk
Quoted 5 lines · Junio C Hamano
Documentation/git-bundle.txt bundle. · line 226
Quoted 3 lines
Documentation/git-bundle.txt +3
-0+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):Are you sure the "except" part is factually correct?
Okay now I get it. Your git-ls-remote(1) example is correct. But I did something like:
``` git clone backup.pack ./repo ```
And clone will not transfer refs/stash. It’s there but it doesn’t seem that convenient to get *out* with a porcelain like git-clone(1). Maybe it’s possible but I kind of want to say “okay just pop your stashes and make regular commits/branches”.
I’m not sure how to formulate that. Seems clumsy:
refs are included in the bundle (also refs/stash but that particular one won't be included in e.g. a clone):
Would it be too drastic to use a footnote?
Signature · 1 line
Kristoffer Haugsbakk
Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example
Quoted 2 lines · Kristoffer Haugsbakk
Maybe it’s possible but I kind of want to say “okay just pop your stashes and make regular commits/branches”.
That requires _more_ than recording the value of the ref for stash, as data for the Nth stash is recorded as the Nth reflog entry for that ref, and the reflog data is not what fetch/push/clone/bundle commands make available.
Quoted 6 lines
I’m not sure how to formulate that. Seems clumsy:
refs are included in the bundle (also
refs/stashbut that particular one won't be included in e.g. a clone):Would it be too drastic to use a footnote?
I am not sure what you want to refer to with "that particular one", but the value of refs/stash does get recorded, and making a mirror clone out of the resulting bundle does give refs/stash with the value of the refs/stash in the original repository where the bundle was taken from. So refs/stash _does_ get included. What is not included is the reflog data for that ref (or any other ref, for that matter).
Because the ref value is transferred via fetch/push/clone/bundle but the reflog (i.e. past values of a ref) data is *not*, "git stash show stash@{4}" is not something you can recreate in the copy of a repository, whether you create the copy with "clone" or "bundle + clone". The story is the same for other refs, and stash is not that special in this regard. "git show master@{yesterday}" in a freshly created copy would give something entirely different from what you would get in the original repository you mirror-cloned or took a bundle from.
You'd need "cp -r" for that.
Re: [PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example
Quoted 35 lines · Junio C Hamano
Quoted 2 lines · Kristoffer Haugsbakk
Maybe it’s possible but I kind of want to say “okay just pop your stashes and make regular commits/branches”.
That requires _more_ than recording the value of the ref for stash, as data for the Nth stash is recorded as the Nth reflog entry for that ref, and the reflog data is not what fetch/push/clone/bundle commands make available.
Quoted 6 lines
I’m not sure how to formulate that. Seems clumsy:
refs are included in the bundle (also
refs/stashbut that particular one won't be included in e.g. a clone):Would it be too drastic to use a footnote?
I am not sure what you want to refer to with "that particular one", but the value of refs/stash does get recorded, and making a mirror clone out of the resulting bundle does give refs/stash with the value of the refs/stash in the original repository where the bundle was taken from. So refs/stash _does_ get included. What is not included is the reflog data for that ref (or any other ref, for that matter).
Because the ref value is transferred via fetch/push/clone/bundle but the reflog (i.e. past values of a ref) data is *not*, "git stash show stash@{4}" is not something you can recreate in the copy of a repository, whether you create the copy with "clone" or "bundle + clone". The story is the same for other refs, and stash is not that special in this regard. "git show master@{yesterday}" in a freshly created copy would give something entirely different from what you would get in the original repository you mirror-cloned or took a bundle from.
Quoted 1 line
You'd need "cp -r" for that.
Thanks. I get it now.
I always forget that the stash uses the reflog.
PATCH v3 2/4 Documentation/git-bundle.txt: remove old `--all` example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We don’t need this part now that we have a fleshed-out --all example.
---
Notes (series):
v3:
• Moved over from previous patch
Removing this mention was first suggested in the following link.
Documentation/git-bundle.txt | 2 -- 1 file changed, 2 deletions(-)
Documentation/git-bundle.txt +0 -2
@@ -202,8 +202,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>`.
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH v3 3/4 Documentation/git-bundle.txt: mention --all in spec. refs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Mention --all as an alternative in “Specifying References”.
--- Documentation/git-bundle.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-bundle.txt +1 -1
@@ -131,7 +131,7 @@ SPECIFYING REFERENCES --------------------- Revisions must be accompanied by reference names to be packaged in a -bundle. +bundle. Alternatively `--all` can be used to package all refs. More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the
Signature · 1 line
2.46.1.641.g54e7913fcb6
PATCH v3 4/4 Documentation/git-bundle.txt: discuss naïve backups
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
Notes (series):
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
v1:
Correct mention of the section? All-caps seems to be the convention.
Documentation/git-bundle.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)
Documentation/git-bundle.txt +18 -0
@@ -337,6 +337,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, 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 -----------
Signature · 1 line
2.46.1.641.g54e7913fcb6
Quoted 7 lines · [email protected] writes:
The details are noted on the patches.
Kristoffer Haugsbakk (4):
Documentation/git-bundle.txt: mention full backup exampleDocumentation/git-bundle.txt: remove old--allexampleDocumentation/git-bundle.txt: mention --all in spec. refsDocumentation/git-bundle.txt: discuss naïve backups
I gave them a cursory read and nothing stood out as iffy. Looked good.
One thing I wondered was, because it is not useful at all to take a "backup" when the user does not know how to restore from the backup, we may have to move things around to stress on _how_ the resulting backup bundle(s) are used to restore the saved state. I haven't applied the patches to review these changes in wider context yet, though.
Thanks.
v4 cover Documentation/git-bundle.txt: promote --all for full backup
In reply to [email protected]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:
Documentation/git-bundle.txt +14 -7
@@ -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
Signature · 1 line
2.47.0
PATCH v4 1/4 Documentation/git-bundle.txt: mention full backup example
From: Kristoffer Haugsbakk <[email protected]>
Provide an example about how to make a “full backup” with caveats about what that means in this case.
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
---
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.
• Add para. describing how to recover the backup
• Correct tense: “transferring”
v3:
• Elaborate on “full backups” in Examples instead
• Just point to the section in the second paragraph where everything is elaborated
• Incorporate some of Junio’s suggestions:
• Mention what the “full backup” here does not include
• Remove the final paragraph pointing to Examples now that we mention it in the second paragraph
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/[email protected]/
Notes (meta-trailers):
Documentation/git-bundle.txt | 37 ++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-)
Documentation/git-bundle.txt +31 -6
@@ -23,8 +23,9 @@ 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 (see the "full backup" example in "EXAMPLES"), and to relay +the state of the references in one repository to another (see the second +example). Git commands that fetch or otherwise "read" via protocols such as `ssh://` and `https://` can also operate on bundle files. It is
@@ -34,8 +35,6 @@ contained within it with linkgit:git-ls-remote[1]. There's no corresponding "write" support, i.e.a 'git push' into a bundle is not supported. -See the "EXAMPLES" section below for examples of how to use bundles. - BUNDLE FORMAT -------------
@@ -216,8 +215,34 @@ bundle. EXAMPLES -------- -Assume you want to transfer the history from a repository R1 on machine A -to another repository R2 on machine B. +We'll discuss two cases: + +1. Taking a full backup of a repository +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: + +---------------- +$ 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, 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. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.
Signature · 1 line
2.47.0
PATCH v4 2/4 Documentation/git-bundle.txt: remove old `--all` example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We don’t need this part now that we have a fleshed-out --all example.
---
Notes (series):
v3:
• Moved over from previous patch
Removing this mention was first suggested in the following link.
Documentation/git-bundle.txt | 2 -- 1 file changed, 2 deletions(-)
Documentation/git-bundle.txt +0 -2
@@ -202,8 +202,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>`.
Signature · 1 line
2.47.0
PATCH v4 3/4 Documentation/git-bundle.txt: mention --all in spec. refs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Mention --all as an alternative in “Specifying References”.
--- Documentation/git-bundle.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-bundle.txt +1 -1
@@ -131,7 +131,7 @@ SPECIFYING REFERENCES --------------------- Revisions must be accompanied by reference names to be packaged in a -bundle. +bundle. Alternatively `--all` can be used to package all refs. More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the
Signature · 1 line
2.47.0
PATCH v4 4/4 Documentation/git-bundle.txt: discuss naïve backups
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
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
v1:
Correct mention of the section? All-caps seems to be the convention.
Documentation/git-bundle.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)
Documentation/git-bundle.txt +18 -0
@@ -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 -----------
Signature · 1 line
2.47.0