[PATCH v3 0/5] Optionally link worktrees with relative paths

[Caleb White <cdwhite3@pm.me>]

Git stores absolute paths when linking worktrees to the main repository.
However, this can cause problems when moving repositories and worktrees,
or when working in containerized environments where absolute paths
differ between systems. The worktree links break, and users are required
to manually execute `worktree repair` to repair them, leading to workflow
disruptions. Additionally, when repositories are mapped inside containers
with different absolute paths, they may become unusable. Repairing
worktrees in the container can then break them outside the container.

In some cases, relative paths can eliminate the need for `worktree repair`.
If both the repository and worktrees are moved together while preserving
their relative locations, the links remain intact. Common examples include
manually moving repositories and worktrees (or by tarballing) or mapping
both inside containers that use different absolute paths.

This patch series introduces the option to link worktrees with relative
paths via the `--relative-paths` argument or the `worktree.useRelativePaths`
config option. Relative paths improve the resilience of worktree links
across systems, especially when worktrees are self-contained in the main
repository (e.g., bare repositories). This enhances portability, improves
workflow efficiency, and reduces the need for manual repair.

Git now supports both absolute and relative paths ensuring backwards
compatibility and offering the flexibility of relative paths when desired.

Signed-off-by: Caleb White <cdwhite3@pm.me>
---
The base for this patch series is obtained by applying the following
patches onto v2.47.0 (777489f9e0):
- <20241021-cleanup-extension-docs-v1-1-ab02cece3132@pm.me> (doc:
  consolidate extensions in git-config documentation, 2024-10-22)
- es/worktree-repair-copied topic (worktree: repair copied repository
  and linked worktrees, 2024-09-23, <20240923075416.54289-1-ericsunshine@charter.net>)

Changes in v4:
- Added <20241021-cleanup-extension-docs-v1-1-ab02cece3132@pm.me> to base
- Updated title to better reflect added functionality.
- Added more test cases
- Added `--relative-paths` option to `git worktree {add,repair}`
- Added `worktree.useRelativePaths` config option.
- Added `relativeWorktrees` extension to prevent older git versions
  from operating on worktrees with relative paths.
- Split patch [2/3] into two patches for easier review: the first
  handles reading potentially relative paths from the files, and the
  second add the cli/config options and handles writing the relative
  paths to the linking files.
- Patch [1/3]: updated infer_backlink() to return -1 on error and
  strbuf.len on success, removed superfluous brackets, added docs,
  updated commit message.
- Improved cover letter and commit messages.
- Added instructions on how to construct the base in the cover letter.
- Link to v3: https://lore.kernel.org/git/20241007-wt_relative_paths-v3-0-622cf18c45eb@pm.me
Changes in v3:
- Squashed patch [3/4] into patch [2/4] to streamline changes.
- Dropped patch [4/4] as it was no longer necessary.
- Rebased onto 20240923075416.54289-1-ericsunshine@charter.net
- Updated `infer_backlink()` to return 1 on success for consistency.
- Swapped the order of `infer_backlink()` arguments for clarity.
- Clear `inferred` if error occurs in `infer_backlink()`.
- Renamed `git_contents` to `dotgit_contents` for clearer semantics.
- Cleaned up `dotgit_contents` logic in `repair_worktree_at_path()`.
- Replaced multiple `xstrfmt/free` calls with a single `strbuf`.
- Added a test case covering a failure noted in a separate patch series.
- Improved commit messages.
- Link to v2: https://lore.kernel.org/r/20241006060017.171788-1-cdwhite3@pm.me
Changes in v2:
- No changes, just a resubmission
- Link to v1: https://lore.kernel.org/git/20241006045847.159937-1-cdwhite3@pm.me/

---
Caleb White (5):
      worktree: refactor infer_backlink() to use strbuf*
      worktree: support worktrees linked with relative paths
      worktree: optionally link worktrees with relative paths
      worktree: add test for path handling in linked worktrees
      worktree: add `relativeWorktrees` extension

 Documentation/config/extensions.txt |   6 +
 Documentation/config/worktree.txt   |   5 +
 Documentation/git-worktree.txt      |   9 ++
 builtin/worktree.c                  |  18 ++-
 repository.c                        |   1 +
 repository.h                        |   1 +
 setup.c                             |   9 +-
 setup.h                             |   1 +
 t/t0001-init.sh                     |  20 ++-
 t/t2400-worktree-add.sh             |  54 +++++++
 t/t2401-worktree-prune.sh           |  20 +++
 t/t2402-worktree-list.sh            |  22 +++
 t/t2403-worktree-move.sh            |  22 +++
 t/t2406-worktree-repair.sh          |  26 ++++
 worktree.c                          | 283 ++++++++++++++++++++++++++----------
 worktree.h                          |  24 +++
 16 files changed, 433 insertions(+), 88 deletions(-)
---
base-commit: 4ec4435df758668055cc904ef64c275bc8d1089b
change-id: 20241007-wt_relative_paths-88f9cf5a070c
prerequisite-change-id: 20241020-cleanup-extension-docs-f365868711bf:v1
prerequisite-patch-id: 60a443b24e92938b9b6f4a016a7bab87e13bf3ea
prerequisite-message-id: <20240923075416.54289-1-ericsunshine@charter.net>
prerequisite-patch-id: 78371f4dbb635e6edab8c51ee7857b903e60df8f

Best regards,
-- 
Caleb White <cdwhite3@pm.me>