An offline Git handover identifies the repository objects and external dependencies needed to reconstruct a named project state.
Direct answer: a repository is one dependency, not the whole handover
A Git bundle can preserve repository objects and references without containing the files represented by Git LFS pointers, the repositories referenced as submodules or the packages needed by a build. Verifying the bundle answers a Git question. Rebuilding the project offline asks a broader question about every dependency required for a named result.
Define that result before collecting material. Identify the exact project state, the required application or build command and the resources the receiver may use. Then reconstruct it on a receiver environment without silently fetching missing resources. Record both successful Git reconstruction and application results. A working checkout alone does not establish that a website, document pipeline or software project can be rebuilt.
This essay proposes the Dependency Boundary Cut: separate resources carried inside Git from resources that need an independently supplied, authorized route. The cut is an author-designed handover method. It does not turn a repository archive into a universal portable environment or imply that credentials and licensed dependencies should be copied indiscriminately.
Key takeaways
Name a commit or another precise project state and the result required from it. A receiver cannot meaningfully test latest without knowing which references and conditions latest refers to. Retain the identity used for the exercise rather than relying on a folder whose name happens to include final.
Distinguish complete bundles from incremental ones. A bundle may require prerequisite commits already present in the receiving repository. Verification can help reveal those prerequisites, but success on the sender's existing machine does not establish that a fresh receiver has them. [S1]
Test without hidden network rescue. A build that silently downloads packages or large objects demonstrates a network-dependent route. That may be useful, but it is different from the offline claim. Observe and record the actual dependency boundary instead of keeping the more impressive label.
The problem: the sender's environment fills the gaps
The sender has usually worked on the project for some time. Their machine may hold package caches, local configuration, downloaded media and credentials that are never part of a commit. Running the project successfully there can make those resources feel like properties of the repository rather than properties of the environment.
An ordinary clone on another connected machine can conceal the same problem in another way. It may obtain missing material from available services during setup. The handover appears self-contained because the downloads happen automatically or are buried in installation output. Disconnecting later reveals the dependency, often when the sender is no longer available.
The root cause is an undefined boundary around the word project. Git describes versioned repository objects. The useful result can depend on resources outside that description. Without a named result and receiving conditions, the two boundaries are easily confused, and a successful transport test becomes an unsupported claim about reconstruction.
Begin with what the receiver must produce or inspect. If the requirement is to browse source history, repository reconstruction may be enough. If the requirement is to build a static website with particular images, the build tools, dependencies and actual media matter too. Make the stronger claim only when its additional dependencies have been exercised.
Definitions and relationship mapping
A Git reference names a point in repository history. A commit identifies a saved project state and links to other repository objects. A bundle packages Git objects and references for transfer, potentially with prerequisites. A working tree is the checked-out file state produced from a repository under the receiving environment.
A submodule relationship records another repository at a particular commit rather than embedding all of that repository's objects in the superproject. Git LFS uses pointer files in Git while storing the larger file content separately. A package dependency can be described by a manifest or lockfile without its actual bytes being present offline.
The reconstruction path is transfer artifact, receiver repository, selected commit, required external objects, working tree and application result. Each transition has a different acceptance question. A complete source history does not automatically provide an application runtime. A dependency manifest identifies a requirement without satisfying it.
An offline boundary specifies which network services are unavailable during the exercise. It should also state the resources already installed or supplied to the receiver. No-network rebuilding on a fully prepared machine is a narrower claim than rebuilding on any machine, and it can still be a useful, repeatable objective.
Framework: the Dependency Boundary Cut
The Dependency Boundary Cut draws a line around what the transferred Git artifact actually carries. On one side are included repository objects and references. On the other are prerequisites, separate repositories, large-file content, build resources and necessary environment assumptions. The point is to classify real dependencies rather than to make the line look impressively small.
First specify the target state and output. Record the commit identity, required references and the concrete operation expected of the receiver. A useful acceptance statement might require building a named static site and opening its selected output pages. This is an illustrative requirement, not a default obligation for every Git handover.
Next inspect the transfer artifact. Use the documented bundle verification procedure in the intended receiving context and resolve prerequisites explicitly. If an incremental bundle assumes history already present, either supply that history through an authorized route or change the artifact. A test in the sender's populated repository cannot stand in for this receiver check.
Then inspect the dependency boundary. Identify submodule commits and obtain their actual repositories where needed. Identify LFS pointers and supply the required large objects through a suitable authorized method. Identify packages, tools, assets and configuration required by the named output. Keep secrets out of an indiscriminate archive; specify their separate authorized provisioning route if the scenario requires them.
Finally reconstruct and exercise the result without unnoticed network access. Record the receiving system, available tools and supplied resources. If a command attempts to fetch something, classify the missing dependency rather than enabling the connection and preserving the offline label. A pass should describe the demonstrated state and conditions precisely enough that another receiver can repeat it.
Three documented examples of repository boundaries
Git's bundle documentation explains that bundles contain objects and references and that some bundles have prerequisite commits. The verify operation checks bundle validity and prerequisites in the receiving repository context. It does not gather untracked files, package installations or every resource needed by the application represented in that history. [S1]
Git's submodule documentation describes the superproject's gitlink and configuration relationship to a separate repository. The superproject records a commit choice; that reference is not the same thing as possessing every required submodule object. An offline receiver needs the relevant separate data as well as the recorded relationship. [S2]
GitHub's Git LFS documentation explains that Git stores a pointer to large-file content while the actual content is stored separately. A transferred repository can therefore contain a valid-looking tracked path whose useful large object has not been supplied to the offline receiver. The pointer and the content need separate inspection. [S3]
These examples are three real documented boundaries, not evidence that a particular project uses all three features. Inspect the project itself. A plain repository with no submodules or LFS may have a simpler Git boundary while still depending on an external compiler, package cache or untracked asset for its intended result.
Case study: source history arrives, the website does not
Consider a hypothetical small publication handing a static-site project to a new maintainer. The receiver must rebuild one named release without network access during the exercise. Counts and observations in this example are illustrative fixtures, not a report of a real organization's performance.
The sender provides a bundle and a brief instruction to check out the release. On the receiver machine, bundle verification reveals a prerequisite from an earlier transfer. The receiver does not have that history. The sender's original verification had passed because their existing repository already contained it. The first failure is a receiver-context mismatch, not a damaged transport file.
After receiving a suitable complete history, the maintainer checks out the target commit. Two images are represented by LFS pointers, and one theme is referenced through a submodule. The files visible in the working tree make the project look almost complete, but neither missing resource can be inferred from a successful bundle verification alone.
The sender supplies the authorized required objects and records their relationship to the chosen commit. A build then attempts to contact a package service because the receiver lacks a necessary dependency. The team keeps the network boundary closed and records that dependency rather than allowing an automatic download to conceal the gap.
Once the permitted tools and required dependency bytes have been supplied, the receiver repeats the build in the stated environment. They inspect three selected output pages and the two consequential images. That result establishes the chosen release's tested reconstruction path, not a guarantee that every historical release or arbitrary machine will build.
The case contains several distinct failures: prerequisite history, separate repository data, large objects and a package dependency. Calling all of them a broken backup would be too vague to guide repair. The boundary cut turns each missing resource into a specific handover item with a responsible owner and a testable receiving result.
Making an offline exercise informative
Separate the collection phase from the exercise. A sender may need authorized network access to assemble resources beforehand. The offline claim concerns what the receiver can do after the stated package and environment are available. Record that preparation instead of implying the project arrived without any external history or service dependency.
Retain the distinction between reproducible and merely successful. A build may finish while embedding timestamps or varying details across environments. If exact output identity is required, define that stronger acceptance rule and investigate the toolchain conditions it needs. Do not invent a reproducibility guarantee from one successful run.
Use an output inspection appropriate to the project. A website may need its pages and assets opened locally. A software project may need a meaningful permitted execution or test. A document pipeline may need its final file inspected. Choose an observable result connected to the receiver's actual task rather than relying only on an exit code.
Do not leave failed attempts mixed invisibly with the accepted environment. Cached downloads from an earlier connected attempt can make a later offline exercise appear self-contained. Either use a fresh stated environment or inventory the resources that remain. The acceptance record should reveal what the successful attempt relied on.
Tradeoff and counterargument: offline completeness can be costly
The strongest objection is that supplying every build dependency can consume more effort than keeping the project on a reliable connected service. That can be a reasonable operating choice. The framework does not demand offline rebuilding for every project; it demands honesty when offline rebuilding is the claim being made.
Define the consequence that justifies the effort. A short source review may require only repository access. A long-lived handover with unavailable upstream services may justify retaining additional dependency material where permitted. The decision should follow the required use and authorized retention scope rather than a general preference for collecting everything.
Some dependencies have distribution, licensing or access constraints. Do not treat technical possibility as permission to bundle them. A documented authorized installation route may be the right arrangement, but if it needs network access the acceptance statement must say so. The boundary can be clear without being entirely offline.
The method cannot promise compatibility with every future operating system or toolchain. It can preserve a tested configuration and explain what was needed at the time. That limited evidence is valuable because future maintainers can see the original assumptions rather than discovering them through a failed rebuild years later.
Common mistakes
Do not equate bundle verification with application acceptance. Do not test incremental prerequisites only in the sender's existing repository. Do not assume a submodule commit reference includes the separate repository or that an LFS pointer is the large object it describes.
Do not call a build offline when setup silently used the network. Do not confuse a dependency lockfile with a retained cache of dependency bytes. Do not package credentials indiscriminately merely because a connected deployment once used them.
Avoid the claim that a source archive proves every historical state rebuildable. Name the tested commit and output. Preserve the difference between a useful source handover, a tested build and exact output reproducibility; each requires additional evidence beyond the preceding achievement.
Action plan: let the receiver reconstruct the chosen release
Write the target commit, required result and offline conditions. Prepare the Git transfer and verify it in the receiver context. Resolve prerequisites from actual observations rather than assumptions about what an earlier handover contained.
Inspect the project for submodules, LFS content and required non-Git resources. Obtain the material through authorized routes and document the receiving environment. Keep sensitive access provisioning separate from the general transfer package.
Reconstruct the project without unnoticed network access, run the agreed operation and inspect its consequential outputs. Record missing resources and repeat after a specific repair. Retain the final dependency boundary, exact project identity and tested result so the next receiver can distinguish what was demonstrated from what remains an assumption.
FAQ: bundles, dependencies and offline claims
The following questions concern a named Git project and receiving scenario. Use the linked documentation for the actual tool versions and inspect the project's own configuration.
Does a Git bundle contain the whole project?
It contains specified Git objects and references, potentially with prerequisites. The useful project can require additional repositories, large objects, tools or other resources. Define the intended result before deciding whether the artifact is sufficient.
What does bundle verify establish?
It checks the bundle and its prerequisites in the relevant receiving repository context. It does not build the application or gather untracked dependencies. Treat its result as one stage of reconstruction rather than a universal completion signal.
Why can verification pass for the sender and fail for the receiver?
The sender may already possess prerequisite history that an incremental bundle assumes. Test the artifact against the intended receiver state. A populated development repository can hide a prerequisite absent from a fresh receiving environment.
Does including all references include untracked files?
No. Git references and objects do not automatically include untracked working material. Inspect which external or untracked resources are actually required and supply only authorized material through an explicit separate route.
Is a submodule already inside the superproject bundle?
The superproject records a relationship to a separate repository commit. The receiver needs the relevant separate objects to reconstruct that dependency. Check the actual submodule setup rather than assuming the recorded path carries all its data.
Why are LFS files sometimes only small text records?
Git LFS stores pointers in Git and keeps large content separately. A pointer can identify a required object without supplying it. Verify that the receiver has the actual content needed by the chosen project state.
Does a lockfile make packages available offline?
A lockfile describes dependency choices; it does not necessarily contain their bytes. Test the actual installation or build route without network access and supply permitted resources needed by that route.
Can setup use the network before the exercise?
It can, if that preparation is authorized and explicitly included in the scenario. The claim should state what was supplied before the offline phase. Do not conceal preparation and imply that any fresh machine can reproduce the result.
What if a required tool cannot be redistributed?
Use an authorized provisioning arrangement and record its requirements. If obtaining it needs a connected service, preserve that limitation in the handover claim rather than copying it without permission or calling the route fully offline.
Is a successful build the same as identical output?
No. A build can finish while its output varies with environment or time. If identical artifacts matter, define and test that stronger requirement. Do not infer byte-for-byte reproducibility from one successful execution.
Should credentials be stored inside the bundle?
Do not make a general transfer package an indiscriminate credential archive. Identify any authorized access needed for the scenario and provision it through the appropriate separate route, with the offline claim limited accordingly.
How should output be checked?
Use the receiver's actual task: open consequential pages, inspect a document or run a meaningful permitted operation. An exit code supports a narrow observation; it does not establish that every intended output is correct or usable.
Can an old connected attempt affect a later offline test?
Yes. Cached downloads or generated files may remain. Use a stated fresh environment or inventory those retained resources so the passing attempt's dependencies are visible rather than supplied by an unexplained earlier run.
Must every historical commit be tested?
Only if that is the actual requirement. A named-release handover can be useful without claiming all history rebuildable. Record the precise state tested and avoid extending its approval to unrelated project versions.
What should remain with the accepted handover?
Keep the commit identity, transfer description, prerequisite findings, separate dependency list, authorized provisioning routes, environment and tested result. Those records explain what the receiver can repeat and what future changes may require another exercise.
Recommended books
Working in Public by Nadia Eghbal examines the human responsibilities surrounding software maintenance. Thinking in Systems by Donella Meadows helps reason about dependencies beyond a visible repository boundary. The Checklist Manifesto by Atul Gawande offers context for concise checks across a coordinated handover. The technical behavior of bundles, submodules and LFS in this essay is established by the linked primary documentation rather than by these books.
Further exploration
After the receiver succeeds, inspect which missing dependency caused the longest uncertainty. Improve that project's handover instructions at the exact boundary discovered. A useful archive does more than retain bytes: it retains enough explanation for an authorized receiver to connect those bytes to a named result, without pretending that every surrounding service has become unnecessary.