[go: up one dir, main page]

Skip to content

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 to HEAD@^ 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 .".

Edited by Dan Allen
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information