Introduction

Using relative paths in a repository is mostly about choosing the right anchor point. The mistake is not usually the path syntax itself. The mistake is assuming every tool resolves relative paths from the same place.

Relative to What

A relative path is always relative to something:

• the current working directory
• the directory containing the current source file
• the repository root
• a configured application base directory

If you do not define that anchor explicitly, the same path can work in one context and fail in another.

For example, data/config.json means something different depending on where the process started.

Prefer File-Based Anchors in Application Code

In application code, the safest pattern is usually to build paths relative to the current source file or a known project root, not relative to the shell's working directory.

Python example:

1from pathlib import Path
2
3BASE_DIR = Path(__file__).resolve().parent
4CONFIG_PATH = BASE_DIR / "resources" / "config.json"
5
6print(CONFIG_PATH.read_text())

This keeps the path stable even if the program is launched from a different directory.

In Node.js with ES modules, the equivalent idea is:

1import { readFileSync } from "node:fs";
2import { fileURLToPath } from "node:url";
3import path from "node:path";
4
5const __filename = fileURLToPath(import.meta.url);
6const __dirname = path.dirname(__filename);
7const configPath = path.join(__dirname, "resources", "config.json");
8
9console.log(readFileSync(configPath, "utf8"));

These examples avoid the fragile assumption that the current working directory is always the repository root.

When Current Working Directory Is Fine

Some tools intentionally run from the repo root:

• build scripts
• task runners
• CI jobs
• package manager commands

In those cases, a repo-root-relative path can be perfectly reasonable. Just be explicit that your script assumes the root.

Shell example:

1#!/usr/bin/env bash
2set -euo pipefail
3
4SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
5REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
6
7cat "$REPO_ROOT/resources/config.json"

This makes the script resilient even if someone runs it from a different directory.

Avoid Hardcoded Absolute Paths

Absolute paths such as /Users/alice/project/assets/logo.png work only on one machine or one deployment layout. They break as soon as another developer clones the repository elsewhere.

Relative or computed paths are better because they preserve portability across:

• local development machines
• CI agents
• containers
• production hosts

Repository code should usually describe path relationships, not specific workstation folder names.

A Good Repository Convention

A clean rule for many teams is:

• source code resolves nearby resources relative to the file that needs them
• scripts that operate on the whole project resolve paths from the repo root
• configuration values override paths only when environment-specific behavior is truly necessary

That gives you predictable behavior without spreading path logic everywhere.

If the project frequently needs the root directory, define it once and pass it down through configuration or a helper function.

Cross-Platform Path Safety

Do not hand-build paths with string concatenation. Use the path library for the language you are in:

• 'pathlib in Python'
• 'path in Node.js'
• 'Path.Combine in .NET'

That avoids separator mistakes and makes code portable between Unix-like systems and Windows.

1using System;
2using System.IO;
3
4string baseDir = AppContext.BaseDirectory;
5string fullPath = Path.Combine(baseDir, "resources", "config.json");
6Console.WriteLine(File.ReadAllText(fullPath));

The exact anchor varies by application type, but the principle stays the same: compute paths structurally instead of concatenating strings.

Common Pitfalls

Assuming relative paths are resolved from the repository root everywhere is the most common mistake. Many programs resolve them from the current working directory instead.

Using ../.. chains everywhere makes the code harder to maintain and usually signals that a clearer anchor should be introduced.

Hardcoding absolute workstation paths makes the repository non-portable for teammates and CI.

Building paths with string concatenation instead of path utilities creates platform-specific bugs, especially on Windows.

Summary

• A relative path is only meaningful when its anchor point is clear.
• In application code, prefer paths derived from the current file or a known base directory.
• In scripts, compute the repo root explicitly instead of assuming the caller's working directory.
• Avoid absolute machine-specific paths inside the repository.
• Use language path utilities so the code stays portable across environments.