Allow git plugins to be specified in the playbook
Currently, to use a custom credential manager, that object must be registered as a plugin (named credentialManager) with the git client (using git.cores). It's possible to register a custom HTTP client as a plugin (named http) using the same approach. The user has to then explicitly require this code using the -r
CLI option (e.g., -r ./my-git-credential-manager.js
).
Not only is this approach a little awkward, there's also no way to support the same code unmodified between Antora 2 and Antora 3 (starting with Antora 3.0.0-alpha.7). That's because after upgrading isomorphic-git, the git.cores API has been removed. While Antora still honors git.cores if defined, the fact remains that the user has to change the way in which the plugin is registered (as described in #774 (comment 599826169)).
If we're going to ask the user to change their code anyway, we might as well make the interchange more elegant. I propose that we allow the git plugins to be defined in the playbook. That way, the user only has to provide a script that exports the plugin rather than having to register the plugin itself using git.cores.
The key will be the name of the plugin and the value the name of the script or module for Antora to require (similar to the provider key in an output destination). These keys must be specified inside the git category.
git:
credentialManager: ./my-git-credential-manager
http: ./my-git-http
We may want to consider nesting these keys inside a plugin category key for clarity:
git:
plugins:
credentialManager: ./my-git-credential-manager
http: ./my-git-http
NOTE: Since isomorphic-git 1.0.0, isomorphic-git doesn't actually recognize a plugin named "credentialManager". However, Antora still uses it to map to the new authentication callbacks in isomorphic-git. So Antora's git plugins aren't necessarily isomorphic-git's plugins.