User Guide

🚀 Quick start

1. Launch Version Tracker. On first launch, a setup assistant guides you through granting Full Disk Access (needed to scan your applications), then optionally installing the package managers you want to track. Everything can be changed later in Settings.
2. Enjoy the free trial. A 7-day trial of the full version starts automatically. No credit card required. When it ends, the app returns to the free version (scanning always remains available).
3. Wait for the first scan. Depending on the number of installed apps and active sources, the initial scan takes 10 to 60 seconds.
4. Check the « All » tab. This is where all available updates from all sources are gathered.
5. Click « Update All » to launch all updates at once, or use the individual buttons to manage each app.

Install with Homebrew

Version Tracker is available from its own Homebrew tap.

brew tap version-tracker/tap
brew install --cask version-tracker/tap/version-tracker

Already installed Version Tracker by hand? Add --force so Homebrew takes over the copy you already have:

brew install --cask --force version-tracker/tap/version-tracker

Version Tracker keeps itself up to date, so brew upgrade will not fight the app's own updater.

🗃️ Supported sources

Version Tracker detects updates for:

Settings → Sources lists the 51 sources with two switches each:

• Active: the source is scanned. Turning it off hides its items and shortens the scan.
• Grouped: the source takes part in Update All, Process All and Download All. Turn it off to keep a source visible and scanned, but out of the big buttons. Its own rows can still be updated one by one.

Grouped is greyed out while Active is off, because a source that is not scanned has nothing to contribute to a batch.

Note: Adobe Camera Raw is a plug-in, not an app, but it is listed and updated with the other Creative Cloud products.

🖥️ The interface

The main screen is divided into three columns, topped by a toolbar:

Left sidebar

Navigation is organized into collapsible sections that you can reorder by drag and drop. The counter next to each category shows how many items it lists, color-coded to tell you what they are (see what the badge colors mean).

• OVERVIEW: Dashboard (overview, recent activity, latest snapshot) and Snapshots
• UPDATES: All (every update in a single list), Apps, Packages, Homebrew, System Updates, Apple Developer Tools, Snoozed (see setting an update aside)…
• Then sections by domain (APPLICATIONS, SYSTEM, AI, JavaScript, Python, Rust, editors…): only those matching what is actually installed on your Mac appear.

Toolbar

• Scan: runs a full scan (the button also lets you cancel a running scan)
• Settings and Feedback: direct access to preferences and the feedback form
• Two buttons to show/hide the sidebar and the Details panel

Center area

The list of items for the selected category, with a search field. Each row shows:

• The app or package icon and name
• The current version and the available version
• A contextual action button (Update, Download, Open, Show in Finder…)

Search covers apps and packages alike, gems, crates, yarn packages and uv tools included. Typing filters straight away, however long your inventory is. Picking a result opens the right category, selects the row and scrolls it into view; an app whose only row is its Homebrew cask lands on that row.

Columns remember every width you set, the name column included, and each table fits its columns to the space available when you resize the window.

Every list says when it was taken, package lists, Adoptable and Ignored included. An empty list explains why it is empty rather than showing nothing.

Right sidebar (Details)

Details for the selected item, spread over four tabs: description, versions, release notes, source, path on disk, and the security checks.

• The Update and Download buttons are here too, not only on the row. A download shows its progress bar, then becomes Show in Finder.
• Copy report puts everything the four tabs know about the item on the clipboard, in one click.
• More actions → Report a wrong detection opens a form already filled in with what Version Tracker saw, so you only have to say what is wrong.
• The panel reopens on the tab you last used, and during a batch it moves straight from one app to the next instead of blanking in between.
• Its buttons are greyed while a scan, a batch or a download is running, like the rows already were.

Note : the window width is remembered between sessions. The minimum size is designed to comfortably display all three columns.

🔄 Updating applications

Individual update

Click the green « Update » button on a row (requires an active license or the trial, see License & trial). Depending on the source:

• Mac App Store: uses CommerceKit (silent background update)
• Homebrew Cask/Formula: runs brew upgrade (with admin authentication if needed, see below). If brew refuses the in-place upgrade, Version Tracker automatically applies the forced reinstall brew recommends.
• Sparkle: downloads the DMG/ZIP, unmounts the old version and installs the new one
• GitHub: downloads and installs the most recent binary
• Direct download: see next section

Automatic backup: when the privileged helper is enabled, the previous version of the app is backed up before every update. If anything goes wrong, restore it from Settings → Backups (retention period and number of copies are adjustable).

Batch update

The « Update All » button in the All view launches every automatable update in sequence, after a confirmation that recaps the number of updates. You can leave the view: the operation continues in the background, and a summary is shown when it finishes (including deferred updates).

You can also select several rows and update just that selection, from the menu.

A batch only takes in the sources whose Grouped switch is on (see Supported sources). Four rules decide what else is left out:

• Running apps and major upgrades are excluded by the safety filter (Settings → Updates). You can still update them one at a time.
• Updates that need a newer macOS than the one you run are excluded, and the row states the version required.
• An update with no signature at all is announced with a warning before anything is installed. An update whose signature fails verification stays blocked, full stop.
• On an Intel Mac, Homebrew formulae that may have to be compiled from source are left out of a global batch, and the report says which ones and why. Update them individually if you want to go ahead: Version Tracker then allows up to eight hours per formula and you can cancel at any point.

If a row fails after its file was already downloaded, the download is handed over to you rather than thrown away: the row offers Show in Finder.

Setting an update aside

An update you do not want right now can be deferred instead of ignored. Right-click the row, choose Defer, and pick how long: 1 day, 3 days, 1 week, 2 weeks, 1 month, or Indefinitely.

The row moves to the Snoozed category in the sidebar, which gathers every app, package and extension whose update is skipped or deferred. It leaves the update lists and the counters, so it stops nagging, but it is never lost: Stop Deferring brings it straight back.

Snoozed is not Ignored. Ignored is for items Version Tracker cannot do anything with. Snoozed is your own decision, with a date attached, and the row returns on its own when the delay runs out.

Manual download (« Download »)

Some apps don't have an automatic mechanism but expose a direct download URL (PKG, DMG, ZIP). For these:

• The orange « Download » button appears
• The file is downloaded to your downloads folder (default ~/Downloads, customizable in Settings)
• Once downloaded, the button becomes « Show in Finder » to finalize installation manually

The « Download all » button starts batch downloads for all eligible apps.

If there's an error (HTTP 403, file not found, etc.), the button switches to « Open »: Version Tracker launches the installed app so it can handle its own update.

📸 Snapshots

The Snapshots view (OVERVIEW section) captures the complete software state of your Mac: applications, packages, tools, installed versions and known updates.

• Create Snapshot (⇧+⌘+N): captures the current inventory. You can then rename or pin it.
• Compare: select two snapshots to see everything that changed between them (installed, removed or updated items), with filters by change type.
• Export…: exports a snapshot or a comparison as JSON, CSV or Markdown. Two privacy profiles: Full (keeps paths and machine name, keep it local) or Shareable (absolute paths, username and machine name are masked).

Typical use cases: documenting a machine before a migration or reinstall, tracking what an update session actually changed, or sharing a clean inventory.

Automatic snapshots

Two options in Settings → Updates:

• Automatic snapshots around “Update All”: creates an inventory snapshot before and after each batch update, to compare and document the changes.
• Snapshot after each scheduled scan: at the end of each automatic scan, creates a snapshot, only if something changed since the last one.

📋 The menu bar

Version Tracker offers a menu bar icon showing the number of pending updates. The icon animates while a scan or an update is running.

The panel

Clicking the icon opens a panel listing the available updates (your version → new version), with:

• Per-row actions: Update, Download or Open depending on the source
• The Scan, Update All and Download All buttons
• A footer with the date of the last scan and the number of tracked items
• A chevron in the header to collapse or expand the list (“Hide the list” / “Show the list”): collapsed, the panel shrinks to its header and footer

Autonomous, even with the app closed

• Open at login (Settings → General): launches only the menu bar icon when your session starts, without opening the main window.
• Updates launched from the panel run in a background process, without opening the main window or the Dock icon.
• With Background Scan (Settings → Automation), scheduled scans, by interval or at a fixed daily time, keep running even when the app is quit: badge and notifications stay up to date.

⚙️ Settings

Settings are organized into panes:

Scanned folders

By default Version Tracker looks where macOS puts applications. Settings → Sources → Scanned folders lets you change that:

• Folders to scan as well: add a folder, a second disk for instance, so your apps there are found too.
• Folders to leave alone: Version Tracker will not look inside.

If the same folder is in both lists, leaving it alone wins. Removing a folder from either list takes it off the list and touches nothing it contains.

Tooltips

Point at a button or a setting and a sentence explains what it does, in the window and in the menu bar panel alike.

Tooltips are off by default in version 1.3. Turn them on in Settings → Appearance → Tooltips. The switch governs the whole app, not one screen out of two.

Hiding the menu bar icon

Settings → General → Hide the menu bar icon removes the icon entirely, whether the window is open or closed. Closing the window then simply hides it, and you reopen it from the Dock or with ⌘+Tab.

Closing the window

• Closing the main window (⌘+W or the red button) hides the window: the app stays active in the background.
• The option « Closing the window keeps only the menu bar » (Settings → General) quits the main app on close and keeps only the menu bar icon.
• ⌘+Q really quits the application (an alert warns you if an update is in progress).

🔐 Administrator authentication

Some updates require administrator privileges. Version Tracker offers two mechanisms:

1. Privileged Helper (recommended): a small signed daemon, enabled once and for all via Settings → General → Privileged Helper → Enable.
2. One-shot authentication: if the helper isn't installed, a system dialog asks for your admin password on each operation.

What the helper brings:

• No more password prompt on every update
• Atomic installation (the app is never left half-replaced)
• Signature and Team ID verification on the root side
• Automatic backup of the previous version before each update

Helper not responding? After an app update, use the « Repair » button in the Privileged Helper pane: it re-registers the daemon without asking for your password again.

🔑 License & trial

Version Tracker follows a freemium model:

• Free version: full scanning and inventory always remain available. You see everything that is outdated, across all sources.
• License (Mono, Solo or Family): unlocks one-click update installs, batch updates and updates from the menu bar. See plans and pricing.
• 7-day free trial: starts automatically on first launch, no credit card required. When the trial ends, the app automatically returns to the free version.

Activating a license: open Settings → License and paste the key received by email after purchase. You can deactivate the license on one Mac to free a seat and activate it on another.

A seat belongs to a user account, not to a Mac. Your key is kept in your login keychain, which macOS keeps separate for each account, so a second account on the same Mac starts with no license and uses a seat of its own when you activate it there. Count one seat per user account that will run Version Tracker.

Lost your license key, or need an invoice? Open My Orders and sign in with your purchase email. No password, just a magic link. It lists every order, your license key, and download files. To manage your subscription (payment method, VAT details, plan changes), use the billing portal instead.

🖱️ Keyboard shortcuts

To run a full scan again, use the Scan button in the toolbar or the Scan button in the menu bar panel.

🌍 Languages

Version Tracker is available in:

• 🇬🇧 English
• 🇫🇷 French
• 🇩🇪 German
• 🇪🇸 Spanish
• 🇵🇹 Portuguese (Portugal)
• 🇮🇹 Italian
• 🇳🇱 Dutch

The language follows macOS system settings automatically, and can be overridden in Settings → General → Language.

🗑️ Uninstalling Version Tracker

Dragging the app to the Trash is enough for most people. Here's the full procedure if you want to leave nothing behind.

Simple method (recommended)

• Open Settings and turn off General → Open at login and Automation → Background Scan.
• Quit Version Tracker and its menu bar icon (click the icon → Quit).
• Drag Version Tracker.app from /Applications to the Trash, then empty the Trash.

No rush : even without this step, any leftover traces are inert. Nothing runs, nothing is root, nothing uses resources.

For a complete removal (optional)

Version Tracker installs three small components, all approved by you at install time : a privileged helper and a menu bar icon (both inside the app, they disappear with it), and a scheduled scan task (a separate file). If you skipped the step above, remove it manually :

launchctl unload ~/Library/LaunchAgents/com.jpflorencio.VersionTracker.agent.plist 2>/dev/null
rm -f ~/Library/LaunchAgents/com.jpflorencio.VersionTracker.agent.plist

To also remove your app backups and inventory snapshots (irreversible) :

rm -rf ~/Library/Application\ Support/Version\ Tracker
defaults delete com.jpflorencio.VersionTracker

Finally, if Version Tracker is still listed in System Settings → General → Login Items & Extensions, remove the entry (it disappears on its own shortly after).

Planning to reinstall or switch Macs?

• Reinstalling on the same Mac : don't touch anything. Your license key stays in the keychain and activates automatically.
• Moving to another Mac : free your activation seat first via Settings → License → Deactivate, before removing the app.

Privileged helper won't reinstall? In System Settings → General → Login Items & Extensions, turn Version Tracker off, then back on (the full cycle resyncs the state: turning it on alone isn't enough). If the problem persists, empty the Trash and restart.

🗑️ Uninstalling package managers

Before you start

• Open the Terminal app (Applications → Utilities). The shell configuration file mentioned below is ~/.zshrc (the macOS default).
• Only remove tools that you installed for Version Tracker. If other software or projects depend on them, keep them.
• Uninstall individual tools first, and Homebrew last: uninstalling it removes all packages installed with it.
• After uninstalling, Version Tracker will simply stop tracking that source. You can reinstall any tool at any time from onboarding or Settings.

1. Tools installed directly by Version Tracker (via Homebrew)

Homebrew will refuse to uninstall if other formulas depend on it. That is a safeguard, not an error.

⚠️ Homebrew (last) removes Homebrew and every package installed with it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

The script lists any residual folders at the end (usually /opt/homebrew on Apple Silicon, /usr/local/Homebrew on Intel).

2. External tools (installed via their official guides)

If you installed any of these with Homebrew instead of the official installer, simply use brew uninstall <formula> instead.

Verify

For each uninstalled tool: command -v <tool> should print nothing (open a new Terminal window first).

❓ Frequently asked questions

📩 Contact

The best place to report a bug or request a feature is the public tracker on GitHub. Every report is visible to everyone, so you can check whether your issue has already been reported, add your own details to it, and follow its progress until it is fixed.

• Bugs and feature requests: open an issue at github.com/Version-Tracker/feedback
• License, billing or private questions: contact@version-tracker.app
• Quick feedback: the Feedback button right inside the app

Reporting a bug? Mention your macOS version, your Version Tracker version, and which app or source is affected. Since the tracker is public, never paste your license key or personal details in an issue: send those by email instead.