diff --git a/.gitignore b/.gitignore
index 7b4a1fb1e..3b77edf1f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,26 +1,19 @@
+## user config
+/Makefile.conf
+
+## build artifacts
+# compiler intermediate files
 *.o
 *.d
 *.dwo
-.*.swp
 *.gch
 *.gcda
 *.gcno
-*~
-__pycache__
-/.cache
-/.cproject
-/.project
-/.settings
-/qtcreator.files
-/qtcreator.includes
-/qtcreator.config
-/qtcreator.creator
-/qtcreator.creator.user
-/compile_commands.json
-/coverage.info
-/coverage_html
-/Makefile.conf
-/viz.js
+*.so.dSYM/
+
+# compiler output files
+/kernel/version_*.cc
+/share
 /yosys
 /yosys.exe
 /yosys.js
@@ -36,22 +29,50 @@ __pycache__
 /yosys-witness-script.py
 /yosys-filterlib
 /yosys-filterlib.exe
-/kernel/*.pyh
-/kernel/python_wrappers.cc
-/kernel/version_*.cc
-/share
 /yosys-win32-mxebin-*
 /yosys-win32-vcxsrc-*
 /yosysjs-*
 /libyosys.so
+
+# build directories
 /tests/unit/bintest/
 /tests/unit/objtest/
 /tests/ystests
+/build
 /result
 /dist
-/*.egg-info
-/build
-/venv
+
+# pyosys
+/kernel/*.pyh
+/kernel/python_wrappers.cc
 /boost
 /ffi
+/venv
 /*.whl
+/*.egg-info
+
+# yosysjs dependency
+/viz.js
+
+# other
+/coverage.info
+/coverage_html
+
+
+# these really belong in global gitignore since they're not specific to this project but rather to user tool choice
+# but too many people don't have a global gitignore configured:
+# https://docs.github.com/en/get-started/git-basics/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer
+__pycache__
+*~
+.*.swp
+/.cache
+/.vscode
+/.cproject
+/.project
+/.settings
+/qtcreator.files
+/qtcreator.includes
+/qtcreator.config
+/qtcreator.creator
+/qtcreator.creator.user
+/compile_commands.json