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 .
".