From 618439ed25b8a8232eeb643392fb686c5a21d096 Mon Sep 17 00:00:00 2001 From: Bob Date: Fri, 2 Oct 2026 03:00:21 +0000 Subject: [PATCH] docs: add post-install next steps and stop-before-update instructions Closes ActivityWatch/docs#94 (updating.rst should explain how to stop ActivityWatch before replacing files) and ActivityWatch/docs#92 (getting-started should mention what to do after installing). - updating.rst: add 'Stop ActivityWatch before updating' section covering aw-qt tray Quit, systemd --user stop, pkill, macOS menu bar / killall, and Windows Task Manager, before the existing macOS-only note. - getting-started.rst: add 'Next steps after installing' section covering the browser extension (with store links), editor watchers (link to watchers.rst), setting up categories (web UI + categories.yaml), and where data lives (link to directories.rst). - docs#170 verified fixed on live site: docs.activitywatch.net search.html loads jquery.js and searchindex.js returns 200; the sphinxcontrib-jquery fix is in production. Git-Session-Id: c8ba --- src/getting-started.rst | 47 +++++++++++++++++++++++++++++++++++++++++ src/updating.rst | 42 ++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) diff --git a/src/getting-started.rst b/src/getting-started.rst index 5acec25..c006193 100644 --- a/src/getting-started.rst +++ b/src/getting-started.rst @@ -51,6 +51,53 @@ If you want more advanced ways to run ActivityWatch (including running it withou .. note:: If you are using a proxy ActivityWatch might not work out of the box. To fix this you can set the environment variable ``NO_PROXY`` to include ``127.0.0.1`` before starting aw-qt. How to set an environment variable depends on your operating system; use Google if you are unsure how to do this. +Next steps after installing +=========================== + +Once ActivityWatch is running and you can see your tray icon, there are a few extra things worth doing to get useful data right away. + +Install the browser extension +----------------------------- + +The default :doc:`watchers` track the active *application* (e.g. ``Firefox``, ``Slack``), but the browser extension — :gh-aw:`aw-watcher-web` — adds the **title and URL of the active tab**. Without it, your browsing history inside the browser shows up as plain ``Firefox`` with no further detail. + +The extension is available for the major browsers: + +- `Chrome / Edge / Brave `_ +- `Firefox `_ + +After installing, pin the extension and reload any tabs you have open so it can start logging. + +.. note:: + The browser extension only runs while its toolbar icon is enabled. If you don't see events from it, click the extension's icon to confirm it is on (its badge colour tells you whether it is currently logging). + +Install an editor watcher +------------------------- + +If you spend a meaningful amount of time in a code or text editor, install the matching editor watcher. Without one, every "coding" minute shows up as the editor's binary name only, with no file, project or language breakdown. + +See the *Editor watchers* section in :doc:`watchers` for the full list (VS Code, Vim/Neovim, JetBrains, Emacs, Sublime, Zed, Obsidian, …). + +Set up categories +----------------- + +ActivityWatch records *what* you were doing but doesn't know what to call it. Categories let you map raw app or window titles onto your own labels (e.g. ``github.com → Coding``, ``Slack → Communication``) so the dashboard can roll activity up by purpose. + +There are two ways to set them up: + +- From the web UI: open ``http://localhost:5600`` → **Settings → Categories** and create a rule. +- From the config file: edit ``categories.yaml`` in your user data directory (see :doc:`directories`); the schema is documented in :doc:`configuration`. + +A useful starter set covers the apps you spend most of your day in; you can always refine later. + +Where your data lives +---------------------- + +Everything ActivityWatch has recorded lives in a per-user directory and survives reinstalls and updates. See :doc:`directories` for the exact paths on Windows, macOS and Linux, and where to find the logs if something goes wrong. + +.. note:: + To back up your data, copy that directory. To start fresh, stop ActivityWatch, delete the directory, and start ActivityWatch again — all your watchers will begin logging from a clean slate. + Autostart ========= diff --git a/src/updating.rst b/src/updating.rst index 9914308..57b6e8a 100644 --- a/src/updating.rst +++ b/src/updating.rst @@ -9,6 +9,48 @@ If you've installed by extracting a folder (Windows/Linux) or ``.app`` bundle (o You do not need to worry about your data disappearing, as it's stored in a separate location (see the :doc:`directories`). +Stop ActivityWatch before updating +---------------------------------- + +Always quit ActivityWatch **before** replacing any files. The bundled ``aw-server`` is a running process that holds the SQLite database open; overwriting its binary or library files while it is running will, on most operating systems, fail silently (or worse, leave you with a half-updated install that crashes on next start). + +How to stop it depends on how you started it: + +.. tabs:: + + .. group-tab:: aw-qt (default) + + Right-click the ActivityWatch tray icon and choose **Quit** (on macOS the tray lives in the menu bar). This stops ``aw-qt`` and the ``aw-server`` it launched. + + .. group-tab:: Linux / systemd --user + + If you started ActivityWatch as a systemd user service, stop it with:: + + systemctl --user stop activitywatch.target + + (or whatever unit name you used; ``systemctl --user list-units | grep activitywatch`` will list them). + + .. group-tab:: Linux / manual + + From a terminal:: + + pkill -f aw-qt + pkill -f aw-server + + Both should exit within a second or two; ``pgrep -f aw-server`` returning nothing confirms the server is stopped. + + .. group-tab:: macOS + + Click the ActivityWatch menu bar icon and choose **Quit**. If the menu bar icon is missing (or you started it from a terminal), run:: + + killall ActivityWatch + killall aw-qt + + .. group-tab:: Windows + + Right-click the ActivityWatch tray icon and choose **Quit**. If the tray icon is not visible, open **Task Manager** (``Ctrl+Shift+Esc``), find the ``aw-qt`` and ``aw-server`` processes, and **End task** each of them before replacing the files. + +After the update, just start ``aw-qt`` (or your usual autostart entry) again — your existing data and buckets are picked up automatically because they live in the standard user data directory (see :doc:`directories`). macOS -----