Issue in the documentation for --reload-include behavior and glob patterns

[arsalanshaikh13]

❗️Problem

The current Uvicorn documentation for --reload-include and --reload-exclude is minimal and lacks critical details about:

• How glob patterns are interpreted.
• The fact that passing --reload-include "*" doesn't behave as expected.
• No examples for common multi-pattern use cases.

---

🧪 Reproduction Steps

Given the following command:

uvicorn main:app  --host 0.0.0.0 --port 8080 --reload --reload-include "*"

Expected behavior: All file changes should trigger reload, including .py, .json, .env, etc.

Actual behavior:

• Error: Got unexpected extra arguments
• in docker-compose it runs without throwing error but there the hidden files get tracked instead of the actual files

---

✅ What Works Instead

This pattern works consistently across platforms:

uvicorn main:app --host 0.0.0.0 --port 8080  --reload \
  --reload-include "*.py" \
  --reload-include "*.json" \
  --reload-include "*.html"

This works fine in shell and docker compose as well

This behavior can be confirmed by reading the source code:
https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/watchfilesreload.py

Notably:

• Default includes: ["*.py"]
• Default excludes: [".*", ".py[cod]", ".sw.*", "~*"]
• --reload-include is additive, not overriding.

---

🔍 What’s Missing in the Docs

The Uvicorn documentation for reload options currently says:

--reload-include <glob-pattern> - Specify a glob pattern to match files or directories which will be watched.

But does not:

• Explain how glob patterns work.
• Mention the default excludes.
• Warn users that "*" does not include dotfiles.
• Provide cross-platform working examples.

---

✅ Suggested Improvements

• Add a full explanation of:

  • How glob matching works using examples similar to example i mentioned under 'What works instead' above for watching .py, .json, .env, .html, etc.
  • Why "*" is not sufficient for all file watching.

---

🙏 Thank You

Thanks for maintaining Uvicorn — it's a fantastic tool. A little more clarity here would go a long way for developers trying to use hot reloading with frontend templates, environment files, or config files.

---