The basic goal of embd is to provide a simple way to "embed" one git repository into another. The prime source of inspiration for this project is the beman-submodule tool, which is implemented in Python and is available on PyPI. embd, on the other hand, is implemented in Rust and will be available as a static binary which provides many options for distribution and installation.
An additional goal of embd is to be more general purpose than beman-submodule, which is more closely tied to the goals and setup that the various Beman projects use.
Both beman-submodule and embd aim to be alternatives to either git submodules or git subtree. Eddie Nolan put together a set of slides to show the differences and limitations of both git subtree and git submodule, so I won't go into that too much here. The gist is that git submodule provides a subpar user experience (users have to remember to run git submodule update --init) and git subtrees force merge commits in your history.
The general idea is to pull the dependent repository as source into the parent repository. This puts the burden of keeping dependencies up to date on the maintainer. embd helps in making that process easier for the maintainer.
| Command | Description | Options |
|---|---|---|
add |
Add a new embedded repo to the project. | folder: Specify what subdirectory to put embed in. \n allow-untracked: Allow untracked files in the embed directory. \n link: The link to the project to include \n rev: Specify the commit,tag or branch to pull \n include: Glob patterns to include \n exclude: Glob patterns to exclude |
update |
Update all embeds to match the config file. | rev: Specify the commit, tag or branch to advance to \n force: Overwrite any local modification \n overwrite: Delete all untracked files (requries force) \n quiet: Print summaries, not each file updates. |
status |
Show the status of all embeds. | quiet: Should summaries per embed, not per file. |
embd keeps a single consolidated file, .embd/embd.toml, describing all the embedded sources. Each entry has a metadata table which includes data like the remote repository URL, commit, folder, and include/exclude filters. The config entry also includes a files table of sha256 hashes per tracked file. This is used to detect local drift without having to re-pull or clone files from the remote.
[repo1.metadata]
remote = "https://example.git"
commit_hash = "123abcd1234"
folder = "example"
allow_untracked = false
[repo1.files]
"a.txt" = "sha256:..."
[repo2.metadata]
remote = "https://example2.git"
commit_hash = "123abcd1234"
folder = "example2"
allow_untracked = false
[repo2.files]
"b.txt" = "sha256:..."