-
Notifications
You must be signed in to change notification settings - Fork 147
Troubleshooting
If you find any errors or error messages confusing - just open an issue asking about them.
Even if you solved a problem and the solution wasn't obvious based on the error - please do share it!
Run guard with the -d option (debugging), which provides more output.
If the plugin is not responding to files at all, you may want to set the LISTEN_GEM_DEBUGGING=1 environment variables (as mentioned here: https://github.com/guard/listen/wiki/Troubleshooting)
You'll know Guard is responding to file changes if you see something like: 20:43:26 - DEBUG - Interactor was stopped or killed.
(If rules in your Guardfile baffle you - check out: https://github.com/guard/guard/wiki/Understanding-Guard).
First, the livereload.js.erb file is processed with Ruby to create a temporary file. This allows custom setting and workarounds in the generated livereload.js. If you supply your own file here, you'll need to restart Guard for changes to take effect.
Guard-livereload start's it's "reactor" (on the port povided) and waits for the browser to connect.
Once this is working, you'll see: "LiveReload is waiting for a browser to connect".
This only means the Guard::LiveReload plugin has finished starting up, nothing more.
If you e.g. have a chrome plugin for LiveReload, then clicking the icon (in the browser's toolbar) to enable LiveReload (the black circle in the icon's middle should get "filled") the extension will try to connect with Guard::LiveReload reactor, listening on the given port (port 35729 by default).
If the extension successfully connects to Guard::LiveReload, you'll see:
"Browser connected."
You can have multiple browsers connect, so this doesn't say how many browsers are connected and currently there's no info when a browser disconnects either (open an issue if you feel this would help).
To be sure, you can switch off the extension and on again - and another "Browser connect." should appear.
Also, at this point, Guard::LiveReload sends a "hello" (literally) command to the extension, to tell it what LiveReload protocol is understood. (You should see this "hello" request in your browser's developer tools).
As in the intro, if this part doesn't work, you may want to first check the README and wiki for the Guard project. Listening to files is quite a tricky feat of technology, and it's hard to work out "what's wrong" without going through a few steps (mentioned there).
Also, specific editors may cause specific problems (each one saves files differently, which can fool Guard and Guard::Listen).
Once Guard detects that a relevant file changed (based on the rules in the Guardfile) ...
The first thing you should see is: "Reloading browser: foobar" (foobar or whatever files changed).
Then Guard::LiveReload sends a "LiveReload reload command" (with info about which files changed) to each listening browser extension.
The command is affected by the liveCSS option (to speed up reloading) and the overrideURL option to help the browsers work out which pages need reloading.
You can probably inspect the requests/commands being sent back and forth in your browser's developer tools (until the page gets actually reloaded - then this info probably disappears).
So the extension then asks Guard::LiveReload to send the JavaScript code (livereload.js) to append to the page. (You can check if the page in your browser has the code snippet - usually at the end of your page).
So Guard::LiveReload is like a web server at this point, which responds to requests with files.
You should see "Browser URL: (...)" which shows which files the browser extension is requesting from Guard::LiveReload.
Aparat from livereload.js, Guard::LiveReload will likely be asked for the files that make up the page (and which have changed), e.g. index.html, foobar.jpg, foobar.css, etc. This also means setting the right content type (e.g. "text/css").
And Guard::LiveReload will happily send those files, or respond with a 404 error if they're not there anymore.
You'll see "Serving file (...)" whenever that happens (but only in Guard debug mode with the -d option).
Usually, though, the extension first asks for livereload.js to add to the page.
The livereload.js contains the code which decides what to reload, how long to wait, etc. It handles a few things like the liveCSS option, handling LESS files, etc.
You can probably add breakpoints in your browser to see what's going on before the reloading.
You can also add debugging statements in your own livereload.js.erb files (and restart Guard if you do). Just copy the livereload.js.erb file into your project and set the :js_template option in your Guardfile.
E.g. if the page is not reloading, you can set JavaScript breakpoints at these functions:
performReload and performAlert
and then you can step through to see why it doesn't go where it should.
In Guard::LiveReload, the last debug message may be like: DEBUG - {:command=>"reload", :path=>"/index.html", :liveCSS=>true}, which means the problem is in the livereload.js file, which for some reason crashed or decided not to reload.
Maybe there are console errors in the browser?
(Let me know if any more specific debugging messages would be helpful).
Anyway, I hope that helps work things out quickly. Feel free to ask questions, because other people probably also have them.
Feel free to improve this wiki if you think it's missing something (or needs corrections, updated).