Use dedicated symbol in branches and worktrees to refer to primary worktree
Instead of overloading . to refer to the primary worktree, introduce a dedicated symbol. The proposed symbol is ^ (taking a page from the git lexicon to mean parent of). By introducing this symbol, it allows . to be reserved for the worktree at the (local) url, which is more consistent with how Antora uses that symbol.
This change will impact the following patterns:
-
worktrees: .- resolves to the worktree at the value of url (aka current worktree)
equivalent to^if url is the primary worktree -
worktrees: ^- resolves to the primary worktree -
branches: HEAD@.- resolves to the branch of the worktree at the value of url
equivalent toHEAD@^if url is the primary worktree -
branches: HEAD@^- resolves to the branch of the primary worktree
Since Antora 3.1 does not support using a linked worktree as a content source, . will always resolve to the primary worktree. Therefore, this does not break compatibility with Antora 3.1.
The default value for worktrees will still remain ., which means the worktree at the value of url. So nothing about the default changes.
An alternate symbol to use would be .. or even ^.. That later might read as "top most .".