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

Message

Caleb White Oct. 25, 2024, 8:57 p.m. UTC

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 <[e-mail]>
---
The base for this patch series is obtained by applying the following
patches onto v2.47.0 (777489f9e0):
- <[e-mail]> (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, <[e-mail]>)

Changes in v4:
- Added <[e-mail]> 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/[e-mail]
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 [e-mail]
- 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/[e-mail]
Changes in v2:
- No changes, just a resubmission
- Link to v1: https://lore.kernel.org/git/[e-mail]/

---
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: <[e-mail]>
prerequisite-patch-id: 78371f4dbb635e6edab8c51ee7857b903e60df8f

Best regards,

Comments

Caleb White Oct. 25, 2024, 8:59 p.m. UTC | #1

My apologies, this should have said v4 instead of v3.

Taylor Blau Oct. 25, 2024, 9:05 p.m. UTC | #2

On Fri, Oct 25, 2024 at 08:57:17PM +0000, Caleb White wrote:
> 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

The previous round was already merged to 'master' a few days ago[1],
after merging it to 'next' and saying so in this[2] WC report.

I'm not sure if you intended to send this series as a follow-up to the
state that was already merged to 'master', or if you had intended to
send a new round of changes not knowing it had already been merged.

In either case, can you please send a new round based on the current tip
of 'master'?

Thanks,
Taylor

[1]: 8e08668322 (Merge branch 'cw/worktree-relative', 2024-10-22).
[2]: https://lore.kernel.org/git/[e-mail]/

Caleb White Oct. 25, 2024, 9:11 p.m. UTC | #3

On Fri Oct 25, 2024 at 4:05 PM CDT, Taylor Blau wrote:
> On Fri, Oct 25, 2024 at 08:57:17PM +0000, Caleb White wrote:
>> 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
>
> The previous round was already merged to 'master' a few days ago[1],
> after merging it to 'next' and saying so in this[2] WC report.
>
> I'm not sure if you intended to send this series as a follow-up to the
> state that was already merged to 'master', or if you had intended to
> send a new round of changes not knowing it had already been merged.
>
> In either case, can you please send a new round based on the current tip
> of 'master'?
>
> Thanks,
> Taylor
>
> [1]: 8e08668322 (Merge branch 'cw/worktree-relative', 2024-10-22).
> [2]: https://lore.kernel.org/git/[e-mail]/

Ah, I must've missed that---I was in the process of working on v4 and
didn't realize that it had already been merged to master.

I'll send a new round based on the current tip of master.

Thanks!
Caleb

Taylor Blau Oct. 25, 2024, 9:38 p.m. UTC | #4

On Fri, Oct 25, 2024 at 09:11:30PM +0000, Caleb White wrote:
> Ah, I must've missed that---I was in the process of working on v4 and
> didn't realize that it had already been merged to master.
>
> I'll send a new round based on the current tip of master.

Thanks.

Looking at the dates, I should have held the existing round in 'next'
for a few days longer. But I figured that the existing v3 was already in
a good state, and hadn't heard otherwise since the original thread[1]
was quiet.

Thanks,
Taylor

[1]: https://lore.kernel.org/git/[e-mail]/

Caleb White Oct. 25, 2024, 10:34 p.m. UTC | #5

On Fri Oct 25, 2024 at 4:38 PM CDT, Taylor Blau wrote:
> On Fri, Oct 25, 2024 at 09:11:30PM +0000, Caleb White wrote:
>> Ah, I must've missed that---I was in the process of working on v4 and
>> didn't realize that it had already been merged to master.
>>
>> I'll send a new round based on the current tip of master.
>
> Thanks.
>
> Looking at the dates, I should have held the existing round in 'next'
> for a few days longer. But I figured that the existing v3 was already in
> a good state, and hadn't heard otherwise since the original thread[1]
> was quiet.
>
> Thanks,
> Taylor
>
> [1]: https://lore.kernel.org/git/[e-mail]/

No worries! I had a busy week and didn't complete v4 as soon I would've
liked. Here is the new round:

https://lore.kernel.org/git/[e-mail]

Best,
Caleb