2.1-syncing-dependencies.md

syncing dependencies

When coming to a project that uses mdm to manage dependencies, use mdm update.

mdm update is a one-stop-shop command that:

• downloads dependencies, if you haven't got them already
• puts the right versions in the current working tree
• cleans up any dependencies that are not required on your current branch

In other words, it puts things where they're supposed to be.

syncing dependencies after a fresh clone

Run mdm update ;)

syncing dependencies after switching branches

Run mdm update ;)

syncing dependencies after pulling changes

Run mdm update ;)

syncing dependencies after checking out an old commit

Run mdm update ;)

so I should run mdm-update every time I build?

Ah, you're seeing the pattern! :)

In short: yeah, that's a pretty safe policy. And there's very little cost to doing so! mdm update typically takes a fraction of a second to run (assuming it already has all downloads out of the way; if it does have to fetch new versions of any dependencies, of course this will depend on your bandwidth).

Either git status or mdm status can tell you if you're out of sync and need to do an mdm update, but quite frankly, it's just as fast to just go ahead and do the mdm update anyway.

git-status can tell you when dependencies are out of sync

Because of mdm's close working relationship with git, git status can tell you when your working tree is not currently sync'd to the version of a dependency that it should be.

Here's a series of examples of what that looks like:

a different version needs to be synced

 $ git status
 # On branch feature/add-stripes-to-go-fast
 # Changes not staged for commit:
 #   (use "git add/rm <file>..." to update what will be committed)
 #   (use "git checkout -- <file>..." to discard changes in working directory)
 #
 #       modified:   lib/pyroclastic (new commits)
 #
 no changes added to commit (use "git add" and/or "git commit -a")

Here, I had switched to a branch that uses a different version of a library. git status reports that lib/pyroclastic is currently checked out to "new commits".

This is because when I switched branches, the hash in git that identifies the desired library version has been switched, but the commit checked out hasn't been changed yet. Running mdm update will check out the correct version of the library.

uncommitted changes are present

If I overwrite one of the files in a dependency, git status will show me a message like this:

 $ git status
 # On branch master
 # Changes not staged for commit:
 #   (use "git add/rm <file>..." to update what will be committed)
 #   (use "git checkout -- <file>..." to discard changes in working directory)
 #   (commit or discard the untracked or modified content in submodules)
 #
 #       modified:   lib/pyroclastic (modified content)
 #
 no changes added to commit (use "git add" and/or "git commit -a")

Or, if there's a new file instead of a changed file...

 $ git status
 # On branch master
 # Changes not staged for commit:
 #   (use "git add/rm <file>..." to update what will be committed)
 #   (use "git checkout -- <file>..." to discard changes in working directory)
 #   (commit or discard the untracked or modified content in submodules)
 #
 #       modified:   lib/pyroclastic (untracked content)
 #
 no changes added to commit (use "git add" and/or "git commit -a")

Like it says on the tin, no? Here, I put a new text file in the path lib/pyroclastic/glacier, and true to form, git's telling me there's untracked content because that file isn't part of the committed stuff.

(Scroll down to the "updating when files have been changed" heading for more on how mdm will behave around these.)

a dependency is not needed

After switching to a branch or an old commit where a dependency is not needed at all, git status will tell me it's now untracked:

 $ git status
 # Not currently on any branch.
 # Untracked files:
 #   (use "git add <file>..." to include in what will be committed)
 #
 #       lib/pyroclastic/
 no changes added to commit (use "git add" and/or "git commit -a")

Running mdm update will remove the lib/pyroclastic directory and its contents from your workspace.

Alternately, git clean -dff is a great command for removing untracked files and directories like this one. (Read the manpage for git-clean before using this.)

Note: when switching to a branch or commit where a dependency is not needed, git may issue you a warning like the following:

 $ git checkout really-old-branch
 warning: unable to rmdir lib/pyroclastic: Directory not empty
 HEAD is now at 24a0d6b... double your interfaces, double your fun

This is "unable to rmdir" warning is because git is paranoid about removing a directory that looks like it contains another git repo (and dependencies managed by mdm look like tiny git repos, because that's indeed exactly what they are). This is totally normal and you can safely ignore it.

Don't worry when removing dependency files, nothing's permanently gone: if you switch back to a branch that needs this dependency and run mdm update again, putting this directory back will still be a fast, local operation, and it will still work completely offline. Just like a git checkout :)

a dependency is needed and missing

git status does not make any comments about missing dependencies. This is because git does not assume all submodules should be fetched and checked out, and mdm dependencies are really just glorified git submodules.

Fortunately, most build processes fail in a predictable and easily recognized way when a dependency is missing, so it's easy to go "D'oh!" and run mdm update to carry on.

mdm status will inform you of any missing dependencies. Also, remember that it's pretty much always safe to just run mdm update as a part of every build, because if the update doesn't have any work to do, it's extremely fast.

updating when files have been changed

mdm steps gingerly whenever uncomitted changes are present in a dependency repo. As usual, this behavior will feel pretty familiar if you're already accustomed to git -- just like git pull, mdm update will refuse to change a dependency if any files have been changed locally, because it doesn't want to risk damaging any of your work.

If mdm doesn't have change a dependency directory, mdm update will completely ignore uncommitted changes on the belief that you know what you're doing.

If mdm does need to change a dependency to bring your workspace in sync, mdm update will abort when it encounters a dependency repo with uncommitted changes.

To throw away any uncommitted changes and get back to a clean workspace state, you can always rm -rf lib/whatever and run mdm update to sync a clean state. (Currently, there is no --force flag to do this for you. Expect it in a future release of mdm, though.)