Upon the very first call, it reloads absolutely all Clojure files on the classpath.
Correction: it doesn't reload ever ns in the classpath. It is limited to directories (as opposed to .clj files contained in .jar files, which also form part of the classpath).
Anyway, that's its behavior when a user hasn't performed
set-refresh-dirs. tools.namespace cannot make a best guess of what the
refresh-dirs value should be, so the best practice is to set it oneself intentfully in advance.
This is reflected in Sierra's reloaded template.
At the very least, it makes the first refresh call much slower than needed.
tools.namespace is aimed at programmers seeking an automated code-reloading, project-oriented workflow.
It assumes that you want to work with your project (as opposed to with an arbitrary set of scripts), and cannot guess which project namespace will be necessary first, or what will you do first (run tests, start a server?). So it loads every ns.
It's worth noting that a REPL session can last days, if not weeks. If something goes wrong, you can
(clear) and start over.
I have some Clojure files on classpath that require dependencies that aren't available. That alone makes it impossible to use refresh.
This issue is entirely gone when using
Of course, the workaround assumes that each files has a proper ns form and doesn't create other namespaces.
That is a good assumption to do for every ns that lives under src, test. Arbitrary tooling can break on namespaces that fail to follow this de-facto standard.
Again, this is why
set-refresh-dirs exists - to distinguish the 'main' source paths (
test/) from other directories containing examples, scripts, drafts, and such. It in fact dangerous to perform
require over arbitrary namespaces in a given project (as those can be production-oriented scripts etc).