# How to Override the Default Tracker File Location in Career-Ops: Complete Guide to CAREER_OPS_TRACKER

> Override CAREER_OPS_TRACKER file location in santifer/career-ops. Set environment variable to specify custom path for applications tracker, ensuring your data is managed where you choose.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Set the `CAREER_OPS_TRACKER` environment variable to specify a custom path for the applications tracker file, which takes precedence over the default [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) location in the santifer/career-ops repository.**

Career-ops manages job application data in a markdown tracker file that defaults to [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) within the repository. According to the source code in `path-resolver.mjs`, you can relocate this tracker to any directory—including network mounts, temporary test folders, or separate data workspaces—by configuring the `CAREER_OPS_TRACKER` environment variable before running any career-ops scripts.

## How the Tracker Path Resolver Works

The source code in `path-resolver.mjs` exports two functions that centralize tracker location logic:

- `resolveTrackerPath(rootDir)` – Used for reading the tracker file
- `resolveTrackerPathForWrite(root)` – Used for writing the tracker file

Both functions check `process.env.CAREER_OPS_TRACKER` before falling back to the default locations. When the environment variable is present, the resolver uses that path directly; otherwise, it searches for [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) or falls back to [`applications.md`](https://github.com/santifer/career-ops/blob/main/applications.md) in the repository root.

### Path Canonicalization for File Locking

Before returning the final path, both resolver functions invoke `canonicalizeTrackerPath` to convert the location into an absolute pathname. This step is essential because `tracker-utils.mjs` implements file-locking mechanisms that require consistent absolute paths across different processes. Without canonicalization, concurrent scripts might resolve the same logical file to different absolute paths, causing race conditions or data corruption.

## Setting the CAREER_OPS_TRACKER Environment Variable

You can override the default tracker file location using shell exports, PowerShell variables, or programmatic assignment in Node.js.

### Bash (Linux, macOS, WSL)

```bash
export CAREER_OPS_TRACKER="/my/custom/workspace/data/applications.md"
node merge-tracker.mjs
node set-status.mjs 42 Applied

```

### PowerShell (Windows)

```powershell
$env:CAREER_OPS_TRACKER = "C:\tmp\career-ops\applications.md"
node test-all.mjs

```

### Node.js Scripts

```javascript
process.env.CAREER_OPS_TRACKER = '/opt/ops/tracker/applications.md';
import { resolveTrackerPath } from './path-resolver.mjs';
const trackerPath = resolveTrackerPath('/opt/ops');
console.log('Using tracker:', trackerPath);

```

## Scripts That Respect the Override

Every script that interacts with the tracker imports from `path-resolver.mjs` and automatically uses the overridden location:

- **`merge-tracker.mjs`** – Merges TSV data into the tracker at the custom location
- **`set-status.mjs`** – Updates row statuses in the overridden tracker file
- **`generate-pdf.mjs`** – Records PDF generation events in the specified tracker

This consistent resolution ensures that whether you are importing data, updating application statuses, or generating documents, all operations target the same tracker file defined by your `CAREER_OPS_TRACKER` setting.

## Summary

- Set `CAREER_OPS_TRACKER` to override the default [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) tracker location in career-ops
- The `resolveTrackerPath()` and `resolveTrackerPathForWrite()` functions in `path-resolver.mjs` give precedence to this environment variable
- Paths are canonicalized to absolute form to ensure consistent file locking via `tracker-utils.mjs`
- All career-ops scripts automatically use the custom location without requiring individual configuration changes

## Frequently Asked Questions

### What is the default tracker file location if CAREER_OPS_TRACKER is not set?

If the environment variable is undefined, the resolver first checks for [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) in the repository root, then falls back to [`applications.md`](https://github.com/santifer/career-ops/blob/main/applications.md) in the root directory. This provides backward compatibility for existing installations while allowing new deployments to specify custom locations immediately.

### Can I use relative paths with CAREER_OPS_TRACKER?

Yes, relative paths are supported. The `canonicalizeTrackerPath` function immediately converts relative paths to absolute paths based on the current working directory, ensuring that the file-locking mechanism in `tracker-utils.mjs` receives a consistent absolute pathname regardless of how the path was initially specified.

### Does the environment variable affect both reading and writing operations?

Yes. The `resolveTrackerPath()` function handles read operations while `resolveTrackerPathForWrite()` handles writes, and both check `process.env.CAREER_OPS_TRACKER` as their first priority. This ensures atomicity and consistency when multiple scripts access the tracker simultaneously.

### How does career-ops prevent conflicts when multiple processes use a custom tracker location?

The `tracker-utils.mjs` module implements locking based on the canonical absolute path returned by the resolver. Since `path-resolver.mjs` ensures all processes resolve the same `CAREER_OPS_TRACKER` value to an identical absolute pathname, the locking mechanism works correctly even when the tracker is located on network drives or shared storage.