| Message ID | e9be866f33daab2d4038f8b3f1140fe41e5f49c5.1730234365.git.code@khaugsbakk.name (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2,1/3] Documentation/git-bundle.txt: mention full backup example | expand |
kristofferhaugsbakk@fastmail.com writes: > From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > 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`. 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? > 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. > diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt > index 3ab42a19cae..0fa181c749d 100644 > --- a/Documentation/git-bundle.txt > +++ b/Documentation/git-bundle.txt > @@ -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(-) diff --git c/Documentation/git-bundle.txt w/Documentation/git-bundle.txt index 3ab42a19ca..633c99c8b2 100644 --- c/Documentation/git-bundle.txt +++ w/Documentation/git-bundle.txt @@ -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
On Sat, Nov 2, 2024, at 02:27, Junio C Hamano wrote: > kristofferhaugsbakk@fastmail.com writes: > >> From: Kristoffer Haugsbakk <code@khaugsbakk.name> >> >> 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`. > > 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). > >> 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. > >> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt >> index 3ab42a19cae..0fa181c749d 100644 >> --- a/Documentation/git-bundle.txt >> +++ b/Documentation/git-bundle.txt >> @@ -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. 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. > > 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. > + > + $ 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. > The 'git bundle verify' command can be used to check whether your > recipient repository has the required prerequisite commits for a
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 3ab42a19cae..0fa181c749d 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -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>`.