When publishing a package from a Git checkout, dart pub publish should include best-effort version-control metadata in the
generated package archive.
Suggested metadata:
"git": {
"commit": "aac20b6e7e543e6dd4118b246c77225e3a3a1302",
"dirty": false
},
"path_in_vcs": "packages/example"
}
This could be stored in a reserved file such as .dart_tool/pub_vcs_info.json or another archive-level metadata location.
Motivation
This would allow consumers and tooling to:
- Locate the source revision associated with a published package.
- Compare revisions associated with different releases.
- Generate changelogs and release diffs.
- Improve dependency auditing and incident investigation.
- Correctly identify packages located inside monorepositories using path_in_vcs.
Cargo provides similar metadata through .cargo_vcs_info.json, containing the checkout hash, dirty state, and repository-relative
package path. Cargo explicitly describes this as best-effort metadata and does not claim that it proves the archive matches the
commit.
Proposed behavior
When creating an archive from a working directory:
- Detect whether the package is inside a Git repository.
- Record the full commit hash.
- Record whether any files included in the package differ from the commit.
- Record the package directory relative to the repository root.
- Omit the metadata if Git information cannot be obtained.
- Preserve the metadata when using --to-archive.
- Do not invent metadata when publishing with --from-archive.
The generated file should not be read from the working tree, preventing publishers from supplying misleading metadata manually.
API and UI
pub.dev could optionally:
- Expose this information through its package-version API.
- Link to the commit when the package’s repository URL identifies a supported public Git host.
- Clearly label dirty publications.
- Avoid linking when the declared repository and detected checkout cannot be associated safely.
Prior art
- npm registry metadata commonly includes a gitHead value.
- Cargo embeds .cargo_vcs_info.json, including commit, dirty state, and path_in_vcs.
Cargo’s documentation explicitly calls this a best-effort snapshot without provenance guarantees: Cargo package documentation
(https://doc.rust-lang.org/cargo/commands/cargo-package.html#cargo_vcs_infojson-format).
When publishing a package from a Git checkout, dart pub publish should include best-effort version-control metadata in the
generated package archive.
Suggested metadata:
This could be stored in a reserved file such as .dart_tool/pub_vcs_info.json or another archive-level metadata location.
Motivation
This would allow consumers and tooling to:
Cargo provides similar metadata through .cargo_vcs_info.json, containing the checkout hash, dirty state, and repository-relative
package path. Cargo explicitly describes this as best-effort metadata and does not claim that it proves the archive matches the
commit.
Proposed behavior
When creating an archive from a working directory:
The generated file should not be read from the working tree, preventing publishers from supplying misleading metadata manually.
API and UI
pub.dev could optionally:
Prior art
Cargo’s documentation explicitly calls this a best-effort snapshot without provenance guarantees: Cargo package documentation
(https://doc.rust-lang.org/cargo/commands/cargo-package.html#cargo_vcs_infojson-format).