[PATCH v4 0/4] Documentation/git-bundle.txt: promote --all for full backup
- From
- kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
- Date
- Nov 16, 2024, 14:54 UTC
- Message-ID
- <cover.1731768344.git.code@khaugsbakk.name>
- In-Reply-To
- <cover.1730979849.git.code@khaugsbakk.name>
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