Copy File Paths for Jira, Confluence, and Technical Documentation on Mac

You're writing a technical spec. It covers a new feature, and to document it properly you need to reference a config template, three design assets, two API handler files, and a handful of component files. Each one needs to appear in the spec so engineers know exactly what they're looking at.

If you're on a Mac and doing this the manual way — hunting through Finder, typing paths from memory, or doing the Option+right-click dance for each file — you're spending real time on something that should be nearly instant. Multiply that by every Jira ticket, every Confluence page, every PR description you write in a week, and it's a meaningful fraction of your writing time.

This guide covers the right path format for each documentation context and the fastest way to get it from Finder.

Jira Tickets — Use Git-Relative Paths

When you're writing a Jira ticket that an engineer will act on, the path reference needs to be immediately useful to anyone on the team. An absolute path like /Users/marcus/projects/app/src/components/Button.tsx is nearly useless in a ticket — it reveals your local checkout path, which is different from every other engineer's machine. The file is in the right place on their machine too; your home directory prefix is noise.

A git-relative path — src/components/Button.tsx — is universal. It works from the repo root on any machine, matches what engineers see in their editor's file tree, and matches what appears in code review diffs. It's also shorter and easier to read at a glance.

Here's what a well-written Jira ticket looks like with proper path references:

Any engineer who reads this knows exactly where to look. No guessing, no grepping. The backtick-wrapped paths also render as code font in Jira's Markdown-style renderer, making them visually distinct and easy to scan.

To get these paths: with Pathly installed, right-click the file in Finder and choose Copy Git Path. Pathly finds the nearest .git directory and computes the path from the repo root automatically. Without Pathly, you'd need to go to Terminal, run git ls-files --full-name filename, and copy the output — several extra steps for each file.

Confluence Pages — Match the Audience

Confluence documentation covers a wider range of file types than Jira tickets, and the right format depends on who's reading and what they'll do with the path.

For code/repo file references

Same rule as Jira: use git-relative paths. If you're writing runbook docs, architecture notes, or onboarding guides that reference specific source files, engineers who clone the repo will find these at the same relative path regardless of where their repo lives.

For server/infrastructure references

When documenting system configuration — Nginx configs, cron jobs, deployment scripts, database configs — absolute paths are exactly right. These files live at fixed system paths that are the same on every server:

Wrapping these in backticks (Confluence supports Markdown-style code formatting) makes them monospace and visually scannable — critical when someone is reading a runbook under pressure at 2am.

For design assets and non-code files

For design files, spreadsheets, or other assets that live outside the repo, the filename alone is often enough context. If the file is in a shared location (Dropbox, Google Drive, a shared network path), link to it instead of referencing a local path. For local assets only you can access, note the folder location but don't pretend the path is useful to others.

GitHub PR Descriptions — Always Git-Relative

This one is clear-cut. GitHub PR descriptions should always use git-relative paths. They:

• Match exactly what reviewers see in the diff tab
• Can be clicked to navigate to the file in GitHub's UI
• Work for any reviewer regardless of whether they have the repo checked out locally
• Are the standard format that engineering teams recognize instantly

This format means reviewers can read the description in their GitHub notifications, understand exactly what changed, and navigate directly to the relevant files. Including your local absolute path (/Users/marcus/...) in a PR description is the most common path format mistake in technical writing — it conveys zero useful information to anyone else and signals that the writer didn't think about portability.

Slack Messages — Filename or Short Path

Slack is a different medium: conversational, skimmable, often read on mobile. The full absolute path adds noise in almost every case. Colleagues don't need to know your home directory structure — they need enough context to understand what you're referring to.

Guidelines for Slack path references:

• Just the filename when it's unambiguous: "the issue is in config.yaml"
• Short git-relative path when there might be ambiguity: "check src/api/config.yaml, not the root one"
• Never absolute paths in Slack — they're long, personal, and unhelpful to the reader

Pathly's Copy Filename option is particularly useful here. One right-click gets you just the filename, ready to paste into Slack without any cleanup.

Quick Reference: Path Format by Context

A Note for Non-Engineers

This guide is written for technical PMs and documentation writers — not just engineers. If you're a PM who writes Jira tickets referencing code locations, a technical writer maintaining runbooks, or a product manager who writes detailed specs with file references, these path formatting choices matter just as much to you as to the engineers on your team.

The file path in a Jira ticket isn't just metadata — it's a direct shortcut to where the work needs to happen. Getting the format right (git-relative, wrapped in backticks, from the repo root) means the engineers reading your tickets can navigate to the right file in under five seconds. Getting it wrong means someone has to decode your local path, strip your home directory, and figure out where the file actually is. It's a small thing, but across hundreds of tickets and pages it's real friction either way.

Pathly makes the format choice automatic: right-click, pick the context-appropriate option, done. The git-relative path is almost always the right choice for documentation that anyone else will read.