From df0cf6faad08fb5a2467c694e1fecec58a5d6df5 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 16 Nov 2024 15:54:51 +0100 Subject: [PATCH 1/4] Documentation/git-bundle.txt: mention full backup example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- 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 3ab42a19ca..b9eb9cef2f 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 +---------------- + +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. From f27b48d9047121ef051267a500cf5982a7b09fc9 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 16 Nov 2024 15:54:52 +0100 Subject: [PATCH 2/4] Documentation/git-bundle.txt: remove old `--all` example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We don’t need this part now that we have a fleshed-out `--all` example. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/git-bundle.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index b9eb9cef2f..917d39356b 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 ``. From c43a67f83d8a8cccfc8b2f2ee7813207136e6dad Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 16 Nov 2024 15:54:53 +0100 Subject: [PATCH 3/4] Documentation/git-bundle.txt: mention --all in spec. refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mention `--all` as an alternative in “Specifying References”. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- 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 917d39356b..eaa16fc4b8 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 From 820fd1a5694b8d96609590163088d3f14731b565 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 16 Nov 2024 15:54:54 +0100 Subject: [PATCH 4/4] =?UTF-8?q?Documentation/git-bundle.txt:=20discuss=20n?= =?UTF-8?q?a=C3=AFve=20backups?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- Documentation/git-bundle.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index eaa16fc4b8..504b8a8143 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 `. This is discouraged since +the repository could be written to during the copy operation. In turn +some files at `` 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 -----------