{"id":17132754,"url":"https://github.com/vduseev/wutch","last_synced_at":"2025-07-24T05:36:48.383Z","repository":{"id":57477839,"uuid":"325541617","full_name":"vduseev/wutch","owner":"vduseev","description":"Watch for changes in the directories, launch shell command on each change and display results in LiveServer. Built with Sphinx in mind. ","archived":false,"fork":false,"pushed_at":"2021-04-10T12:59:25.000Z","size":5563,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-14T01:39:54.887Z","etag":null,"topics":["live-reload","livereload","liveserver","python","refresh","shell","sphinx-doc"],"latest_commit_sha":null,"homepage":"https://wutch.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vduseev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-30T12:10:27.000Z","updated_at":"2024-02-27T05:09:13.000Z","dependencies_parsed_at":"2022-09-10T08:21:54.315Z","dependency_job_id":null,"html_url":"https://github.com/vduseev/wutch","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/vduseev/wutch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vduseev%2Fwutch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vduseev%2Fwutch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vduseev%2Fwutch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vduseev%2Fwutch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vduseev","download_url":"https://codeload.github.com/vduseev/wutch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vduseev%2Fwutch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266796900,"owners_count":23985493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["live-reload","livereload","liveserver","python","refresh","shell","sphinx-doc"],"created_at":"2024-10-14T19:28:11.104Z","updated_at":"2025-07-24T05:36:48.354Z","avatar_url":"https://github.com/vduseev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wutch\n\n`wutch` watches for changes in the directories and runs a shell command for\nevery change. It can also open a browser a display whatever is in the build\ndirectory, just like Live Server.\n\nCommon use case for Wutch involves writing docs with [Sphinx][sphinx]. Wutch will\nwatch for the changes in all `*.rst` files and automatically rebuild documentation.\nIt will also open a browser window pointing to the build directory and inject\nevery built webpage with a code that will auto-refresh that page after each\nrebuild.\n\n\u003cp\u003e\n    \u003ca href=\"https://pypi.org/project/wutch/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/wutch?color=blue\u0026logo=pypi\"\u003e\u003c/a\u003e\n    \u003ca href='https://wutch.readthedocs.io/en/latest/?badge=latest'\u003e\u003cimg src='https://readthedocs.org/projects/wutch/badge/?version=latest' alt='Documentation Status' /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n![Wutch Demo](https://github.com/vduseev/wutch/raw/master/docs/_static/wutch-demo.gif)\n\n* [Documentation](https://wutch.readthedocs.io/en/latest/)\n* [Getting Started (Blog post)](https://duseev.com/articles/introducing-wutch/)\n\n## Installation\n\n```shell\npip install wutch\n```\n\n## Usage\n\nJust run wutch in the directory where you want to watch for the changes.\nBy default, `wutch` will:\n\n* Watch for every change in the current directory.\n* Ignore changes in the `_build/` and `build` directories.\n* Run `sphinx-build` shell command for every change in the files.\n* Open a browser pointing to `index.html` in the `_build` directory.\n* Automatically refresh that page every time you change the files\n  and shell command runs.\n\n```shell\n$ wutch -vvv\n\n2021-04-10 12:33:16.367 | DEBUG    | wutch.watcher:start:25 - Starting observer thread\n2021-04-10 12:33:16.368 | DEBUG    | wutch.watcher:on_any_event:58 - Processing event \u003cFileModifiedEvent: event_type=modified, src_path='docs', is_directory=False\u003e.\nrm -rf \"_build\"\n#@poetry run sphinx-build -M build \".\" \"_build\"\nRunning Sphinx v3.5.3\nloading translations [en]... done\nmaking output directory... done\nbuilding [mo]: targets for 0 po files that are out of date\nbuilding [html]: targets for 1 source files that are out of date\nupdating environment: [new config] 1 added, 0 changed, 0 removed\nreading sources... [100%] index\nlooking for now-outdated files... none found\npickling environment... done\nchecking consistency... done\npreparing documents... done\nwriting output... [100%] index\ngenerating indices... genindex done\nwriting additional pages... search done\ncopying static files... done\ncopying extra files... done\ndumping search index in English (code: en)... done\ndumping object inventory... done\nbuild succeeded.\n\nThe HTML pages are in _build/html.\n2021-04-10 12:33:17.627 | DEBUG    | wutch.watcher:on_any_event:71 - Shell command executed with result: None.\n2021-04-10 12:33:17.627 | DEBUG    | wutch.events:report:15 - New Event.ShellCommandFinished event has been reported.\n2021-04-10 12:33:17.627 | DEBUG    | wutch.watcher:start:28 - Observer thred started\n2021-04-10 12:33:17.628 | DEBUG    | wutch.server:start:44 - Server thread started\n2021-04-10 12:33:17.628 | DEBUG    | wutch.server:open_browser:137 - Opening browser at: http://localhost:5010/index.html\n```\n\nStop wutch by issuing a \u003ckbd\u003eCtrl+C\u003c/kbd\u003e key sequence.\n\n```shell\n^C2021-04-10 12:33:28.396 | DEBUG    | wutch.threaded:run:28 - Stopping all threads on KeyboardInterrupt\n2021-04-10 12:33:28.397 | DEBUG    | wutch.watcher:stop:32 - Stopping observer thread\n2021-04-10 12:33:28.560 | DEBUG    | wutch.watcher:stop:35 - Observer thread stopped\n2021-04-10 12:33:28.560 | DEBUG    | wutch.server:stop:58 - Server thread stopped\n```\n\n## Configuration\n\n### Parameters\n\n```shell\n-h, --help            show this help message and exit\n-c COMMAND, --command COMMAND\n                    Shell command executed in response to file changes. Defaults to: sphinx-build.\n-C CONFIG, --config CONFIG\n                    Path to the wutch config file. Defaults to: wutch.cfg.\n-d [DIRS ...], --dirs [DIRS ...]\n                    Directories to watch (separated by ' '). Defaults to: ['.'].\n-p [PATTERNS ...], --patterns [PATTERNS ...]\n                    Matches paths with these patterns (separated by ' '). Defaults to: ['*'].\n-P [IGNORE_PATTERNS ...], --ignore-patterns [IGNORE_PATTERNS ...]\n                    Ignores changes in files that match these patterns (separated by ' '). Defaults to: ['_build/', 'build/'].\n-w WAIT, --wait WAIT  Wait N seconds after the command is finished before refreshing the web page. Defaults to: 1.\n-b BUILD, --build BUILD\n                    Build directory containing files to render in the browser. Defaults to: _build/html.\n-I [INJECT_PATTERNS ...], --inject-patterns [INJECT_PATTERNS ...]\n                    Patterns of files to inject with JS code that refreshes them on rebuild (separated by ' '). Defaults to: ['*.htm*'].\n-i INDEX, --index INDEX\n                    File that will be opened in the browser with the start of the watcher. Defaults to: index.html.\n--host HOST           Host to bind internal HTTP server to. Defaults to: localhost.\n--port PORT           TCP port to bind internal HTTP server to. Defaults to: 5010.\n-B, --no-browser      Do not open browser at wutch launch. Defaults to: False.\n-S, --no-server       Do not start the webserver, just launch the shell command. Defaults to: False.\n-v, --verbose         Log verbosity. Has four levels: error, wargning, info, and debug. Can be stacked: -v (for warning) or -vvv (for debug).\n-V, --version         Display version of the wutch.\n```\n\n### Loading order\n\nWutch loads configuration settings in the following priority:\n\n1. Command line arguments\n2. Environment variables starting with `WUTCH_`\n3. Configuration file `wutch.cfg`\n4. Default variables\n\nEvery variable can be specified in any of the sources above, thanks to\n[`ilexconf`][ilexconf] configuration management library.\n\nFor example, `dirs` variable that lists directories to watch can be\nspecified in several ways:\n\n**Command line:**\n\n```shell\nwutch --dirs . ../other_dir\n```\n\n**Environment variables starting with `WUTCH_`:**\n\n```shell\nexport WUTCH_DIRS=\". ../other_dir\"\n```\n\n**Configuration file `wutch.cfg`:**\n\n```json\n{\n    \"dirs\": [\".\", \"../other_dir\"]\n}\n```\n\n## Wutch's documentation is built using `wutch`\n\nTake a look at the `wutch.cfg` file at the root of the repository. This\nserves as a somewhat common configuration for Sphinx dependent documentation.\n\nWutch documentation is developed using `wutch` and this config below.\n\n```json\n{\n    \"dirs\": [\"docs\"],\n    \"patterns\": [\"*.rst\", \"*.py\"],\n    \"ignore_patterns\": [\"docs/_build/\"],\n    \"command\": \"make -C docs rebuild\",\n    \"build\": \"docs/_build/html\",\n    \"inject_patterns\": [\"*.html\"],\n    \"index\": \"index.html\",\n    \"host\": \"localhost\",\n    \"port\": 5010\n}\n```\n\n[sphinx]: https://www.sphinx-doc.org/ \"Sphinx\"\n[ilexconf]: https://github.com/ilexconf/ilexconf \"Ilexconf\"","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvduseev%2Fwutch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvduseev%2Fwutch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvduseev%2Fwutch/lists"}