{ "content": [ { "type": "text", "text": "# git-bundle (man)\n\n## NAME\n\ngit-bundle - Move objects and refs by archive\n\n## SYNOPSIS\n\ngit bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n[--version=] \ngit bundle verify [-q | --quiet] \ngit bundle list-heads [...]\ngit bundle unbundle [--progress] [...]\n\n## DESCRIPTION\n\nCreate, unpack, and manipulate \"bundle\" files. Bundles are used for the \"offline\" transfer of\nGit objects without an active \"server\" sitting on the other side of the network connection.\n\n## TLDR\n\n> Package objects and references into an archive.\n\n- Create a bundle file that contains all objects and references of a specific branch:\n `git bundle create {{path/to/file.bundle}} {{branch_name}}`\n- Create a bundle file of all branches:\n `git bundle create {{path/to/file.bundle}} --all`\n- Create a bundle file of the last 5 commits of the current branch:\n `git bundle create {{path/to/file.bundle}} -5 {{HEAD}}`\n- Create a bundle file of the latest 7 days:\n `git bundle create {{path/to/file.bundle}} --since 7.days {{HEAD}}`\n- Verify that a bundle file is valid and can be applied to the current repository:\n `git bundle verify {{path/to/file.bundle}}`\n- Print to `stdout` the list of references contained in a bundle:\n `git bundle unbundle {{path/to/file.bundle}}`\n- Unbundle a specific branch from a bundle file into the current repository:\n `git pull {{path/to/file.bundle}} {{branch_name}}`\n- Create a new repository from a bundle:\n `git clone {{path/to/file.bundle}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **BUNDLE FORMAT**\n- **OPTIONS** (4 subsections)\n- **SPECIFYING REFERENCES**\n- **OBJECT PREREQUISITES**\n- **EXAMPLES**\n- **GIT**\n- **NOTES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "git-bundle", "section": "", "mode": "man", "summary": "git-bundle - Move objects and refs by archive", "synopsis": "git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n[--version=] \ngit bundle verify [-q | --quiet] \ngit bundle list-heads [...]\ngit bundle unbundle [--progress] [...]", "tldr_summary": "Package objects and references into an archive.", "tldr_examples": [ { "description": "Create a bundle file that contains all objects and references of a specific branch", "command": "git bundle create {{path/to/file.bundle}} {{branch_name}}" }, { "description": "Create a bundle file of all branches", "command": "git bundle create {{path/to/file.bundle}} --all" }, { "description": "Create a bundle file of the last 5 commits of the current branch", "command": "git bundle create {{path/to/file.bundle}} -5 {{HEAD}}" }, { "description": "Create a bundle file of the latest 7 days", "command": "git bundle create {{path/to/file.bundle}} --since 7.days {{HEAD}}" }, { "description": "Verify that a bundle file is valid and can be applied to the current repository", "command": "git bundle verify {{path/to/file.bundle}}" }, { "description": "Print to `stdout` the list of references contained in a bundle", "command": "git bundle unbundle {{path/to/file.bundle}}" }, { "description": "Unbundle a specific branch from a bundle file into the current repository", "command": "git pull {{path/to/file.bundle}} {{branch_name}}" }, { "description": "Create a new repository from a bundle", "command": "git clone {{path/to/file.bundle}}" } ], "tldr_source": "official", "flags": [ { "flag": "", "long": "--progress", "arg": null, "description": "Progress status is reported on the standard error stream by default when it is attached to a terminal, unless -q is specified. This flag forces progress status even if the standard error stream is not directed to a terminal." }, { "flag": "", "long": "--all-progress", "arg": null, "description": "When --stdout is specified then progress report is displayed during the object count and compression phases but inhibited during the write-out phase. The reason is that in some cases the output stream is directly linked to another command which may wish to display progress status of its own as it processes incoming pack data. This flag is like --progress except that it forces progress report for the write-out phase as well even if --stdout is used." }, { "flag": "", "long": "--all-progress-implied", "arg": null, "description": "This is used to imply --all-progress whenever progress display is activated. Unlike --all-progress this flag doesn’t actually force any progress display by itself. --version= Specify the bundle version. Version 2 is the older format and can only be used with SHA-1 repositories; the newer version 3 contains capabilities that permit extensions. The default is the oldest supported format, based on the hash algorithm in use." }, { "flag": "-q", "long": "--quiet", "arg": null, "description": "This flag makes the command not to report its progress on the standard error stream." } ], "examples": [ "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.", "To bootstrap the process, you can first create a bundle that does not have any prerequisites.", "You can use a tag to remember up to what commit you last processed, in order to make it easy", "to later update the other repository with an incremental bundle:", "machineA$ cd R1", "machineA$ git bundle create file.bundle master", "machineA$ git tag -f lastR2bundle master", "Then you transfer file.bundle to the target machine B. Because this bundle does not require", "any existing object to be extracted, you can create a new repository on machine B by cloning", "from it:", "machineB$ git clone -b master /home/me/tmp/file.bundle R2", "This will define a remote called \"origin\" in the resulting repository that lets you fetch and", "pull from the bundle. The $GITDIR/config file in R2 will have an entry like this:", "[remote \"origin\"]", "url = /home/me/tmp/file.bundle", "fetch = refs/heads/*:refs/remotes/origin/*", "To update the resulting mine.git repository, you can fetch or pull after replacing the bundle", "stored at /home/me/tmp/file.bundle with incremental updates.", "After working some more in the original repository, you can create an incremental bundle to", "update the other repository:", "machineA$ cd R1", "machineA$ git bundle create file.bundle lastR2bundle..master", "machineA$ git tag -f lastR2bundle master", "You then transfer the bundle to the other machine to replace /home/me/tmp/file.bundle, and", "pull from it.", "machineB$ cd R2", "machineB$ git pull", "If you know up to what commit the intended recipient repository should have the necessary", "objects, you can use that knowledge to specify the prerequisites, giving a cut-off point to", "limit the revisions and objects that go in the resulting bundle. The previous example used", "the lastR2bundle tag for this purpose, but you can use any other options that you would give", "to the git-log(1) command. Here are more examples:", "You can use a tag that is present in both:", "$ git bundle create mybundle v1.0.0..master", "You can use a prerequisite based on time:", "$ git bundle create mybundle --since=10.days master", "You can use the number of commits:", "$ git bundle create mybundle -10 master", "You can run git-bundle verify to see if you can extract from a bundle that was created with a", "prerequisite:", "$ git bundle verify mybundle", "This will list what commits you must have in order to extract from the bundle and will error", "out if you do not have them.", "A bundle from a recipient repository’s point of view is just like a regular repository which", "it fetches or pulls from. You can, for example, map references when fetching:", "$ git fetch mybundle master:localRef", "You can also see what references it offers:", "$ git ls-remote mybundle" ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "DESCRIPTION", "lines": 14, "subsections": [] }, { "name": "BUNDLE FORMAT", "lines": 17, "subsections": [] }, { "name": "OPTIONS", "lines": 34, "subsections": [ { "name": "--progress", "lines": 4, "long": "--progress" }, { "name": "--all-progress", "lines": 7, "long": "--all-progress" }, { "name": "--all-progress-implied", "lines": 8, "long": "--all-progress-implied" }, { "name": "-q, --quiet", "lines": 2, "flag": "-q", "long": "--quiet" } ] }, { "name": "SPECIFYING REFERENCES", "lines": 32, "subsections": [] }, { "name": "OBJECT PREREQUISITES", "lines": 30, "subsections": [] }, { "name": "EXAMPLES", "lines": 88, "subsections": [] }, { "name": "GIT", "lines": 2, "subsections": [] }, { "name": "NOTES", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "git-bundle - Move objects and refs by archive\n", "subsections": [] }, "SYNOPSIS": { "content": "git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n[--version=] \ngit bundle verify [-q | --quiet] \ngit bundle list-heads [...]\ngit bundle unbundle [--progress] [...]\n\n", "subsections": [] }, "DESCRIPTION": { "content": "Create, unpack, and manipulate \"bundle\" files. Bundles are used for the \"offline\" transfer of\nGit objects without an active \"server\" sitting on the other side of the network connection.\n\nThey can be used to create both incremental and full backups of a repository, and to relay\nthe state of the references in one repository to another.\n\nGit commands that fetch or otherwise \"read\" via protocols such as ssh:// and https:// can\nalso operate on bundle files. It is possible git-clone(1) a new repository from a bundle, to\nuse git-fetch(1) to fetch from one, and to list the references contained within it with git-\nls-remote(1). There’s no corresponding \"write\" support, i.e.a git push into a bundle is not\nsupported.\n\nSee the \"EXAMPLES\" section below for examples of how to use bundles.\n", "subsections": [] }, "BUNDLE FORMAT": { "content": "Bundles are .pack files (see git-pack-objects(1)) with a header indicating what references\nare contained within the bundle.\n\nLike the the packed archive format itself bundles can either be self-contained, or be created\nusing exclusions. See the \"OBJECT PREREQUISITES\" section below.\n\nBundles created using revision exclusions are \"thin packs\" created using the --thin option to\ngit-pack-objects(1), and unbundled using the --fix-thin option to git-index-pack(1).\n\nThere is no option to create a \"thick pack\" when using revision exclusions, and users should\nnot be concerned about the difference. By using \"thin packs\", bundles created using\nexclusions are smaller in size. That they’re \"thin\" under the hood is merely noted here as a\ncuriosity, and as a reference to other documentation.\n\nSee the bundle-format documentation[1] for more details and the discussion of \"thin pack\" in\nthe pack format documentation[2] for further details.\n", "subsections": [] }, "OPTIONS": { "content": "create [options] \nUsed to create a bundle named file. This requires the arguments to\ndefine the bundle contents. options contains the options specific to the git bundle\ncreate subcommand.\n\nverify \nUsed to check that a bundle file is valid and will apply cleanly to the current\nrepository. This includes checks on the bundle format itself as well as checking that the\nprerequisite commits exist and are fully linked in the current repository. git bundle\nprints a list of missing commits, if any, and exits with a non-zero status.\n\nlist-heads \nLists the references defined in the bundle. If followed by a list of references, only\nreferences matching those given are printed out.\n\nunbundle \nPasses the objects in the bundle to git index-pack for storage in the repository, then\nprints the names of all defined references. If a list of references is given, only\nreferences matching those in the list are printed. This command is really plumbing,\nintended to be called only by git fetch.\n\n\nA list of arguments, acceptable to git rev-parse and git rev-list (and containing a named\nref, see SPECIFYING REFERENCES below), that specifies the specific objects and references\nto transport. For example, master~10..master causes the current master reference to be\npackaged along with all objects added since its 10th ancestor commit. There is no\nexplicit limit to the number of references and objects that may be packaged.\n\n[...]\nA list of references used to limit the references reported as available. This is\nprincipally of use to git fetch, which expects to receive only those references asked for\nand not necessarily everything in the pack (in this case, git bundle acts like git\nfetch-pack).\n", "subsections": [ { "name": "--progress", "content": "Progress status is reported on the standard error stream by default when it is attached\nto a terminal, unless -q is specified. This flag forces progress status even if the\nstandard error stream is not directed to a terminal.\n", "long": "--progress" }, { "name": "--all-progress", "content": "When --stdout is specified then progress report is displayed during the object count and\ncompression phases but inhibited during the write-out phase. The reason is that in some\ncases the output stream is directly linked to another command which may wish to display\nprogress status of its own as it processes incoming pack data. This flag is like\n--progress except that it forces progress report for the write-out phase as well even if\n--stdout is used.\n", "long": "--all-progress" }, { "name": "--all-progress-implied", "content": "This is used to imply --all-progress whenever progress display is activated. Unlike\n--all-progress this flag doesn’t actually force any progress display by itself.\n\n--version=\nSpecify the bundle version. Version 2 is the older format and can only be used with SHA-1\nrepositories; the newer version 3 contains capabilities that permit extensions. The\ndefault is the oldest supported format, based on the hash algorithm in use.\n", "long": "--all-progress-implied" }, { "name": "-q, --quiet", "content": "This flag makes the command not to report its progress on the standard error stream.\n", "flag": "-q", "long": "--quiet" } ] }, "SPECIFYING REFERENCES": { "content": "Revisions must be accompanied by reference names to be packaged in a bundle.\n\nMore than one reference may be packaged, and more than one set of prerequisite objects can be\nspecified. The objects packaged are those not contained in the union of the prerequisites.\n\nThe git bundle create command resolves the reference names for you using the same rules as\ngit rev-parse --abbrev-ref=loose. Each prerequisite can be specified explicitly (e.g.\n^master~10), or implicitly (e.g. master~10..master, --since=10.days.ago master).\n\nAll of these simple cases are OK (assuming we have a \"master\" and \"next\" branch):\n\n$ git bundle create master.bundle master\n$ echo master | git bundle create master.bundle --stdin\n$ git bundle create master-and-next.bundle master next\n$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n\n\nAnd so are these (and the same but omitted --stdin examples):\n\n$ git bundle create recent-master.bundle master~10..master\n$ git bundle create recent-updates.bundle master~10..master next~5..next\n\n\nA revision name or a range whose right-hand-side cannot be resolved to a reference is not\naccepted:\n\n$ git bundle create HEAD.bundle $(git rev-parse HEAD)\nfatal: Refusing to create empty bundle.\n$ git bundle create master-yesterday.bundle master~10..master~5\nfatal: Refusing to create empty bundle.\n\n", "subsections": [] }, "OBJECT PREREQUISITES": { "content": "When creating bundles it is possible to create a self-contained bundle that can be unbundled\nin a repository with no common history, as well as providing negative revisions to exclude\nobjects needed in the earlier parts of the history.\n\nFeeding a revision such as new to git bundle create will create a bundle file that contains\nall the objects reachable from the revision new. That bundle can be unbundled in any\nrepository to obtain a full history that leads to the revision new:\n\n$ git bundle create full.bundle new\n\n\nA revision range such as old..new will produce a bundle file that will require the revision\nold (and any objects reachable from it) to exist for the bundle to be \"unbundle\"-able:\n\n$ git bundle create full.bundle old..new\n\n\nA self-contained bundle without any prerequisites can be extracted into anywhere, even into\nan empty repository, or be cloned from (i.e., new, but not old..new).\n\nIt is okay to err on the side of caution, causing the bundle file to contain objects already\nin the destination, as these are ignored when unpacking at the destination.\n\nIf you want to match git clone --mirror, which would include your refs such as\nrefs/remotes/*, use --all. If you want to provide the same set of refs that a clone directly\nfrom the source repository would get, use --branches --tags for the .\n\nThe git bundle verify command can be used to check whether your recipient repository has the\nrequired prerequisite commits for a bundle.\n", "subsections": [] }, "EXAMPLES": { "content": "Assume you want to transfer the history from a repository R1 on machine A to another\nrepository R2 on machine B. For whatever reason, direct connection between A and B is not\nallowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to\nupdate R2 with development made on the branch master in R1.\n\nTo bootstrap the process, you can first create a bundle that does not have any prerequisites.\nYou can use a tag to remember up to what commit you last processed, in order to make it easy\nto later update the other repository with an incremental bundle:\n\nmachineA$ cd R1\nmachineA$ git bundle create file.bundle master\nmachineA$ git tag -f lastR2bundle master\n\n\nThen you transfer file.bundle to the target machine B. Because this bundle does not require\nany existing object to be extracted, you can create a new repository on machine B by cloning\nfrom it:\n\nmachineB$ git clone -b master /home/me/tmp/file.bundle R2\n\n\nThis will define a remote called \"origin\" in the resulting repository that lets you fetch and\npull from the bundle. The $GITDIR/config file in R2 will have an entry like this:\n\n[remote \"origin\"]\nurl = /home/me/tmp/file.bundle\nfetch = refs/heads/*:refs/remotes/origin/*\n\n\nTo update the resulting mine.git repository, you can fetch or pull after replacing the bundle\nstored at /home/me/tmp/file.bundle with incremental updates.\n\nAfter working some more in the original repository, you can create an incremental bundle to\nupdate the other repository:\n\nmachineA$ cd R1\nmachineA$ git bundle create file.bundle lastR2bundle..master\nmachineA$ git tag -f lastR2bundle master\n\n\nYou then transfer the bundle to the other machine to replace /home/me/tmp/file.bundle, and\npull from it.\n\nmachineB$ cd R2\nmachineB$ git pull\n\n\nIf you know up to what commit the intended recipient repository should have the necessary\nobjects, you can use that knowledge to specify the prerequisites, giving a cut-off point to\nlimit the revisions and objects that go in the resulting bundle. The previous example used\nthe lastR2bundle tag for this purpose, but you can use any other options that you would give\nto the git-log(1) command. Here are more examples:\n\nYou can use a tag that is present in both:\n\n$ git bundle create mybundle v1.0.0..master\n\n\nYou can use a prerequisite based on time:\n\n$ git bundle create mybundle --since=10.days master\n\n\nYou can use the number of commits:\n\n$ git bundle create mybundle -10 master\n\n\nYou can run git-bundle verify to see if you can extract from a bundle that was created with a\nprerequisite:\n\n$ git bundle verify mybundle\n\n\nThis will list what commits you must have in order to extract from the bundle and will error\nout if you do not have them.\n\nA bundle from a recipient repository’s point of view is just like a regular repository which\nit fetches or pulls from. You can, for example, map references when fetching:\n\n$ git fetch mybundle master:localRef\n\n\nYou can also see what references it offers:\n\n$ git ls-remote mybundle\n\n", "subsections": [] }, "GIT": { "content": "Part of the git(1) suite\n", "subsections": [] }, "NOTES": { "content": "1. the bundle-format documentation\nfile:///usr/share/doc/git/html/technical/bundle-format.html\n\n2. the pack format documentation\nfile:///usr/share/doc/git/html/technical/pack-format.html\n\n\n\nGit 2.34.1 02/26/2026 GIT-BUNDLE(1)", "subsections": [] } } } }