[PATCH 0/4] Documentation/git-bundle.txt: promote --all for full backup

[PATCH 0/4] Documentation/git-bundle.txt: promote --all for full backup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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
-- 
2.46.1.641.g54e7913fcb6

[PATCH 1/4] Documentation/git-bundle.txt: mention --all in Synopsis

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Long line in bundle.c now?

 Documentation/git-bundle.txt | 2 +-
 builtin/bundle.c             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 3ab42a19cae..7579dd309ac 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git bundle' create [-q | --quiet | --progress]
-		    [--version=<version>] <file> <git-rev-list-args>
+		    [--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>...]
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 127518c2a8d..6d610253575 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -17,7 +17,7 @@
 
 #define BUILTIN_BUNDLE_CREATE_USAGE \
 	N_("git bundle create [-q | --quiet | --progress]\n" \
-	   "                  [--version=<version>] <file> <git-rev-list-args>")
+	   "                  [--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 \
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH 1/4] Documentation/git-bundle.txt: mention --all in Synopsis

[Kristoffer Haugsbakk]

On Sun, Oct 20, 2024, at 21:14, kristofferhaugsbakk@fastmail.com 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.

-- 
  Kristoffer Haugsbakk
  kristofferhaugsbakk@fastmail.com

Re: [PATCH 1/4] Documentation/git-bundle.txt: mention --all in Synopsis

[Taylor Blau]

On Sun, Oct 20, 2024 at 09:33:39PM +0200, Kristoffer Haugsbakk wrote:
> On Sun, Oct 20, 2024, at 21:14, kristofferhaugsbakk@fastmail.com 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.

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

[kristofferhaugsbakk]

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

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-bundle.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7579dd309ac..bf0d448a736 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH 2/4] Documentation/git-bundle.txt: mention full backup example

[Taylor Blau]

On Sun, Oct 20, 2024 at 09:15:00PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> 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`.
>
> 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

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

> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-bundle.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 7579dd309ac..bf0d448a736 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -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

[Kristoffer Haugsbakk]

On Mon, Oct 21, 2024, at 23:32, Taylor Blau wrote:
> On Sun, Oct 20, 2024 at 09:15:00PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>> 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`.
>>
>> 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
>
> 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.

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

-- 
  Kristoffer Haugsbakk
  kristofferhaugsbakk@fastmail.com

[PATCH 3/4] Documentation/git-bundle.txt: mention --all in spec. refs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention `--all` as an alternative in “Specifying References”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-bundle.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index bf0d448a736..cf25e6e8540 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH 3/4] Documentation/git-bundle.txt: mention --all in spec. refs

[Taylor Blau]

On Sun, Oct 20, 2024 at 09:15:01PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Mention `--all` as an alternative in “Specifying References”.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index cf25e6e8540..b5cc4746b45 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -----------
 
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH 0/4] Documentation/git-bundle.txt: promote --all for full backup

[Taylor Blau]

On Sun, Oct 20, 2024 at 09:14:58PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> +Cc is just `./contrib/contacts/git-contacts` minus Junio.

Ævar, who you CC'd here is currently inactive[^1], so it may be unlikely
that we receive a response from him.

> 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

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.

Re: [PATCH 0/4] Documentation/git-bundle.txt: promote --all for full backup

[Taylor Blau]

On Sun, Oct 20, 2024 at 09:14:58PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 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

Re: [PATCH 0/4] Documentation/git-bundle.txt: promote --all for full backup

[Kristoffer Haugsbakk]

On Tue, Oct 22, 2024, at 19:29, Taylor Blau wrote:
> On Sun, Oct 20, 2024 at 09:14:58PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> 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?

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)

[PATCH v2 0/3] Documentation/git-bundle.txt: promote --all for full backup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The documentation for git-bundle(1) now properly covers `--all`, the
option from git-rev-list(1) that can be used to package all refs.  A
"Discussions" section has also been added to address the naive backup
strategy of copying a Git repository manually with cp(1) or some other
non-Git tool.

---

The part above was for the-topic-summary.

I was prompted by SO questions like this one:

    https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo

I then compared VonC’s answer to the man page.  The first thing I
noticed was that `--all` wasn’t in the synopsis.

+Cc is just `./contrib/contacts/git-contacts` minus Junio.  (Although he
is inactive (from v1); keeping Cc on the series since it is customary)

Cheers

§ Changes in v2

• Patch v1 1/4: drop
• Patch v2 1/3: combine with previous paragraph and drop “mirror”
  sentence
• Patch v2 3/3: fix `make lint-docs` failure

Kristoffer Haugsbakk (3):
  Documentation/git-bundle.txt: mention full backup example
  Documentation/git-bundle.txt: mention --all in spec. refs
  Documentation/git-bundle.txt: discuss naïve backups

 Documentation/git-bundle.txt | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index b5cc4746b45..7bffd2e4a05 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git bundle' create [-q | --quiet | --progress]
-		    [--version=<version>] <file> (<git-rev-list-args> | --all)
+		    [--version=<version>] <file> <git-rev-list-args>
 'git bundle' verify [-q | --quiet] <file>
 'git bundle' list-heads <file> [<refname>...]
 'git bundle' unbundle [--progress] <file> [<refname>...]
@@ -23,11 +23,8 @@ the "offline" transfer of Git objects without an active "server"
 sitting on the other side of the network connection.
 
 They can be used to create both incremental and full backups of a
-repository, and to relay the state of the references in one repository
-to another.
-
-You can use `git bundle create <file> --all` to create a full backup of
-your repository.
+repository (`git bundle create <file> --all`), and to relay the state of
+the references in one repository to another.
 
 Git commands that fetch or otherwise "read" via protocols such as
 `ssh://` and `https://` can also operate on bundle files. It is
@@ -206,8 +203,6 @@ It is okay to err on the side of caution, causing the bundle file
 to contain objects already in the destination, as these are ignored
 when unpacking at the destination.
 
-If you want to match `git clone --mirror`, which would include your
-refs such as `refs/remotes/*`, use `--all`.
 If you want to provide the same set of refs that a clone directly
 from the source repository would get, use `--branches --tags` for
 the `<git-rev-list-args>`.
@@ -335,7 +330,7 @@ some files at `<destination>` could be corrupted.
 This is why it is recommended to use Git tooling for making repository
 backups, either with this command or with e.g. linkgit:git-clone[1].
 
-See also linkgit:gitfaq[1], section "TRANSFERS" for a discussion of the
+See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
 problems associated with file syncing across systems.
 
 FILE FORMAT
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 6d610253575..127518c2a8d 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -17,7 +17,7 @@
 
 #define BUILTIN_BUNDLE_CREATE_USAGE \
 	N_("git bundle create [-q | --quiet | --progress]\n" \
-	   "                  [--version=<version>] <file> (<git-rev-list-args> | --all)")
+	   "                  [--version=<version>] <file> <git-rev-list-args>")
 #define BUILTIN_BUNDLE_VERIFY_USAGE \
 	N_("git bundle verify [-q | --quiet] <file>")
 #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
Range-diff against v1:
1:  39bdc5941c7 ! 1:  e9be866f33d Documentation/git-bundle.txt: mention --all in Synopsis
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    Documentation/git-bundle.txt: mention --all in Synopsis
    +    Documentation/git-bundle.txt: mention full backup example
     
    -    `--all` is convenient for bundling all refs.  But it is only mentioned
    -    once, halfway through the doc, under the demure section “Object
    -    prerequisites”.  It deserves to be mentioned as an alternative to
    -    `<git-rev-list-args>`.
    +    Tell the user how to make a full backup of the repository right at the
    +    start of the doc.
    +
    +    This is a requested use-case.[1]  But the doc is a bit unassuming
    +    about it:
    +
    +      “ If you want to match `git clone --mirror`, which would include your
    +        refs such as `refs/remotes/*`, use `--all`.
    +
    +    The user cannot be expected to formulate “I want a full backup” as “I
    +    want to match `git clone --mirror`” for a bundle file or something.
    +    Let’s drop this mention of `--all` later in the doc and frontload it.
    +
    +    † 1: E.g.:
    +
    +        • https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo
    +        • https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    -    Long line in bundle.c now?
    +    v2:
    +    • Mention as a parenthetical on an existing paragraph (don’t create a
    +      new sentence and paragraph)
    +    • Remove the “mirror” mention
    +
    +      Link (both): https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/
     
      ## Documentation/git-bundle.txt ##
    -@@ Documentation/git-bundle.txt: SYNOPSIS
    - --------
    - [verse]
    - 'git bundle' create [-q | --quiet | --progress]
    --		    [--version=<version>] <file> <git-rev-list-args>
    -+		    [--version=<version>] <file> (<git-rev-list-args> | --all)
    - 'git bundle' verify [-q | --quiet] <file>
    - 'git bundle' list-heads <file> [<refname>...]
    - 'git bundle' unbundle [--progress] <file> [<refname>...]
    -
    - ## builtin/bundle.c ##
    -@@
    +@@ Documentation/git-bundle.txt: the "offline" transfer of Git objects without an active "server"
    + sitting on the other side of the network connection.
    + 
    + They can be used to create both incremental and full backups of a
    +-repository, and to relay the state of the references in one repository
    +-to another.
    ++repository (`git bundle create <file> --all`), and to relay the state of
    ++the references in one repository to another.
    + 
    + Git commands that fetch or otherwise "read" via protocols such as
    + `ssh://` and `https://` can also operate on bundle files. It is
    +@@ Documentation/git-bundle.txt: It is okay to err on the side of caution, causing the bundle file
    + to contain objects already in the destination, as these are ignored
    + when unpacking at the destination.
      
    - #define BUILTIN_BUNDLE_CREATE_USAGE \
    - 	N_("git bundle create [-q | --quiet | --progress]\n" \
    --	   "                  [--version=<version>] <file> <git-rev-list-args>")
    -+	   "                  [--version=<version>] <file> (<git-rev-list-args> | --all)")
    - #define BUILTIN_BUNDLE_VERIFY_USAGE \
    - 	N_("git bundle verify [-q | --quiet] <file>")
    - #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
    +-If you want to match `git clone --mirror`, which would include your
    +-refs such as `refs/remotes/*`, use `--all`.
    + If you want to provide the same set of refs that a clone directly
    + from the source repository would get, use `--branches --tags` for
    + the `<git-rev-list-args>`.
2:  f7d9aa89c95 < -:  ----------- Documentation/git-bundle.txt: mention full backup example
3:  33980a47d13 = 2:  f18f8ca453d Documentation/git-bundle.txt: mention --all in spec. refs
4:  63a431537b7 ! 3:  c50f9d405f9 Documentation/git-bundle.txt: discuss naïve backups
    @@ Commit message
     
     
      ## Notes (series) ##
    +    v2:
    +    • Fix gitfaq(7) link
    +
    +      Link: https://lore.kernel.org/git/ZxfhAAgNlbEq60VB@nand.local/#t
    +    v1:
         Correct mention of the section?  All-caps seems to be the convention.
     
      ## Documentation/git-bundle.txt ##
    @@ Documentation/git-bundle.txt: You can also see what references it offers:
     +This is why it is recommended to use Git tooling for making repository
     +backups, either with this command or with e.g. linkgit:git-clone[1].
     +
    -+See also linkgit:gitfaq[1], section "TRANSFERS" for a discussion of the
    ++See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the
     +problems associated with file syncing across systems.
     +
      FILE FORMAT

base-commit: 34b6ce9b30747131b6e781ff718a45328aa887d0
-- 
2.46.1.641.g54e7913fcb6

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

[kristofferhaugsbakk]

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

The user cannot be expected to formulate “I want a full backup” as “I
want to match `git clone --mirror`” for a bundle file or something.
Let’s drop this mention of `--all` later in the doc and frontload it.

† 1: E.g.:

    • https://stackoverflow.com/questions/5578270/fully-backup-a-git-repo
    • https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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/ZxbIWEGS1UB3UIg+@nand.local/

 Documentation/git-bundle.txt | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

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>`.
-- 
2.46.1.641.g54e7913fcb6

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

[Junio C Hamano]

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

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

[Kristoffer Haugsbakk]

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

[PATCH v2 2/3] Documentation/git-bundle.txt: mention --all in spec. refs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention `--all` as an alternative in “Specifying References”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-bundle.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 0fa181c749d..bce62bc8309 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.46.1.641.g54e7913fcb6

[PATCH v2 3/3] Documentation/git-bundle.txt: discuss naïve backups

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Fix gitfaq(7) link
    
      Link: https://lore.kernel.org/git/ZxfhAAgNlbEq60VB@nand.local/#t
    v1:
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index bce62bc8309..7bffd2e4a05 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -----------
 
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH v2 3/3] Documentation/git-bundle.txt: discuss naïve backups

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

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

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

Re: [PATCH v2 0/3] Documentation/git-bundle.txt: promote --all for full backup

[Taylor Blau]

On Tue, Oct 29, 2024 at 09:41:43PM +0100, kristofferhaugsbakk@fastmail.com wrote:
> 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(-)

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

[PATCH v3 0/4] Documentation/git-bundle.txt: promote --all for full backup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7bffd2e4a05..ad9ab3247f5 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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 <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## 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/xmqqh68q1l37.fsf@gitster.g/
    +        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/#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/ZxbIWEGS1UB3UIg+@nand.local/
     
    +
    + ## Notes (meta-trailers) ##
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
    +        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/
    +
      ## 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
-- 
2.46.1.641.g54e7913fcb6

[PATCH v3 1/4] Documentation/git-bundle.txt: mention full backup example

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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/xmqqh68q1l37.fsf@gitster.g/
        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/#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)
    • Remove the “mirror” mention
    
      Link (both): https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/

Notes (meta-trailers):
    Helped-by: Junio C Hamano <gitster@pobox.com>
        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/

 Documentation/git-bundle.txt | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 3ab42a19cae..f39cafee927 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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.
-- 
2.46.1.641.g54e7913fcb6

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

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

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

and 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 stash

and see that refs/stash gets propagated.

Fix is a simple s/except/including/ ;-)

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

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.

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

[Kristoffer Haugsbakk]

On Fri, Nov 8, 2024, at 03:01, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>> +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.

Sure.  I should be able to fit in a paragraph about using that
backup bundle.

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

[Kristoffer Haugsbakk]

On Sun, Nov 10, 2024, at 20:38, Kristoffer Haugsbakk wrote:
> On Fri, Nov 8, 2024, at 03:01, Junio C Hamano wrote:
>>> +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?

-- 
Kristoffer Haugsbakk

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

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

> 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?

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

[Kristoffer Haugsbakk]

On Tue, Nov 12, 2024, at 23:58, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>> 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.
>
>> 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?
>
> 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.

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We don’t need this part now that we have a fleshed-out `--all` example.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3:
    • Moved over from previous patch
    
      Removing this mention was first suggested in the following link.
    
      Link: https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/

 Documentation/git-bundle.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f39cafee927..724534a330f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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>`.
-- 
2.46.1.641.g54e7913fcb6

[PATCH v3 3/4] Documentation/git-bundle.txt: mention --all in spec. refs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention `--all` as an alternative in “Specifying References”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-bundle.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 724534a330f..d95bdd0429c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.46.1.641.g54e7913fcb6

[PATCH v3 4/4] Documentation/git-bundle.txt: discuss naïve backups

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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
    
      Link: https://lore.kernel.org/git/ZxfhAAgNlbEq60VB@nand.local/#t
    v1:
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index d95bdd0429c..ad9ab3247f5 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -----------
 
-- 
2.46.1.641.g54e7913fcb6

Re: [PATCH v3 0/4] Documentation/git-bundle.txt: promote --all for full backup

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> 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

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.

[PATCH v4 0/4] Documentation/git-bundle.txt: promote --all for full backup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index ad9ab3247f5..504b8a8143a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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/xmqqh68c3vr8.fsf@gitster.g/
    +    • Add para. describing how to recover the backup
    +
    +      Link: https://lore.kernel.org/git/xmqq1pzmqy97.fsf@gitster.g/
    +    • 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
-- 
2.47.0

[PATCH v4 1/4] Documentation/git-bundle.txt: mention full backup example

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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/xmqqh68c3vr8.fsf@gitster.g/
    • Add para. describing how to recover the backup
    
      Link: https://lore.kernel.org/git/xmqq1pzmqy97.fsf@gitster.g/
    • 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
    
        Link: https://lore.kernel.org/git/xmqqh68q1l37.fsf@gitster.g/
        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/#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)
    • Remove the “mirror” mention
    
      Link (both): https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/

Notes (meta-trailers):
    Helped-by: Junio C Hamano <gitster@pobox.com>
        Link: https://lore.kernel.org/git/xmqqzfmiza69.fsf@gitster.g/

 Documentation/git-bundle.txt | 37 ++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 3ab42a19cae..b9eb9cef2f8 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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.
-- 
2.47.0

[PATCH v4 2/4] Documentation/git-bundle.txt: remove old `--all` example

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We don’t need this part now that we have a fleshed-out `--all` example.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3:
    • Moved over from previous patch
    
      Removing this mention was first suggested in the following link.
    
      Link: https://lore.kernel.org/git/ZxbIWEGS1UB3UIg+@nand.local/

 Documentation/git-bundle.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index b9eb9cef2f8..917d39356bb 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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>`.
-- 
2.47.0

[PATCH v4 3/4] Documentation/git-bundle.txt: mention --all in spec. refs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention `--all` as an alternative in “Specifying References”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-bundle.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 917d39356bb..eaa16fc4b83 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.47.0

[PATCH v4 4/4] Documentation/git-bundle.txt: discuss naïve backups

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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
    
      Link: https://lore.kernel.org/git/ZxfhAAgNlbEq60VB@nand.local/#t
    v1:
    Correct mention of the section?  All-caps seems to be the convention.

 Documentation/git-bundle.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index eaa16fc4b83..504b8a8143a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -----------
 
-- 
2.47.0