You probably already know that Nix Flakes does not recognize files in your project if you do not track them by Git, and if you do not want to add them directly, you can use the --intent-to-add flag:

git add --intent-to-add <file>

This makes Git track the file, but it is not staged. Example:

$ touch file
$ git add --intent-to-add file
$ git status -s file
 A file

So it will not be part of your next commit, but it will be registered to Flakes.

Recently, I was packaging a few NPM packages for my workflow migration. I ran into an issue with pkgs.buildNpmPackage where this section of the package.json was causing an issue (minimized):

{
  "scripts": {
    "copy-python": "mkdir -p lib/python && cp -r python/* lib/python/",
  }
}

Specifically:

> > mkdir -p lib/python && cp -r python/* lib/python/
>
> cp: cannot stat 'python/*': No such file or directory

This confused me because the python directory clearly existed in the root and was tracked by Git:

$ git ls-files python
python/mcp-bridge

When I inspected the type of directory, I saw that it was a submodule, so I assumed that was related:

$ git submodule status
 97f3c0d411065258679ee8d56f270fc5c7fc1a98 python/mcp-bridge (remotes/origin/feat/mcpm-aider)

I first assumed that it wasn't pulled, so I naturally ran:

$ git submodule update --init --recursive

But that didn't resolve the issue. Turns out that Nix Flakes does not copy submodule directories either, even though they are part of Git.

To fix this, you just have to supply the ?submodules=1 attribute:

$ nix run ".?submodules=1"

Obviously, make sure that you use the quotes because your shell may have issues:

$ nix run .?submodules=1
zsh: no matches found: .?submodules=1

If you use nix-direnv for your projects, you can integrate this into your .envrc:

use flake '.?submodules=1'

Hope this helps other people if they happen to be stuck with a situation like this.