On Sat, Nov 2, 2024, at 02:27, Junio C Hamano wrote:
> kristofferhaugsbakk@xxxxxxxxxxxx writes:
>
>> From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
>>
>> 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
