Re: [PATCH v2 1/3] Documentation/git-bundle.txt: mention full backup example

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Nov 6, 2024, 19:31 UTC
Message-ID: <9ce2d94d-2baf-416a-9368-502d08886f9b@app.fastmail.com>
In-Reply-To: <xmqqh68q1l37.fsf@gitster.g>

On Sat, Nov 2, 2024, at 02:27, Junio C Hamano wrote:

Show 15 quoted lines

> 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).

Show 31 quoted 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 `--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.

Show 10 quoted 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.

Show 7 quoted lines

> +
> +    $ 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