git checkout with different node_modules folder

I suffered the problem too. And my workaround is using git worktree. Create linked working tree for each branch, put the node_modules in it instead of main working tree.

See this similar question: Switch node_modules folder when I change git branch

This article explains why it is better than git clone: https://spin.atomicobject.com/2016/06/26/parallelize-development-git-worktrees/

This is not possible in git. By definition untracked files are part of file system and not git's version control.

git checkout

Updates files in the working tree to match the version in the index or the specified tree. If no paths are given, git checkout will also update HEAD to set the specified branch as the current branch.

So when you checkout a branch you just get the working copy of files in that branch. Since untracked files like node_modules are not part of any specific branch but the local file system it will remain as it is.

I also had to choose git worktree for this purpose. Below is how I was able to do it in step-by-step.

1. Create the gh-pages branch as an orphan branch. git checkout --orphan gh-pahes

2. Create a git worktree off the gh-pages branch.
   git worktree add <worktree_name> gh-pages

3. A new directory will have been created with the name <worktree_name> by now. cd to that folder and run npm install. Changing the directory to this folder equals checking out the gh-pages branch.

4. Now you can develop your Github Pages site and push it to gh-pages branch of the remote to deploy it.

I'm having a similar problem as well as this can also be an issue when upgrading the dependencies listed in the package.json (another branch may still have the old package.json in which case modules in node_modules could be at the wrong versions after switching branches).

One of my ideas is to setup a local git checkout hook which runs npm ci every time I switch/checkout different branches or commits. This requires having/using and tracking/committing a package-lock.json however, plus (re)installing might take too long on bigger projects (in which case you may want to try something like pnpm in order to speed up installs).

Another idea is to simply use yarn v2 and then commit all of your dependencies/modules (which I believe yarn stores locally in what it calls its cache). Also, I could be wrong but I believe you can also run npm ls and it will error if node_modules does not match the project/package manifests (not sure if this is well-documented however, nor do I know much about the finer details of what it does and doesn't verify).