Add {branch} option to gitRevision

Resolves #3041

Author: Gerrit0

CHANGELOG.md

@@ -6,6 +6,8 @@ title: Changelog
 
 ### Features
 
+- The `gitRevision` option now accepts the special value `{branch}`, which indicates source links should use
+ the current git branch for links, #3041.
 - Introduced `validation.invalidPath` for suppressing warnings caused by referencing relative paths which
  do not exist when building the documentation, #3033.
 - API: Introduced `Logger.validationWarning` for validation which occurs during conversion rather than

site/options/input.md

@@ -297,11 +297,13 @@ placeholders.
 ## gitRevision
 
 ```bash
-typedoc --gitRevision <revision|branch>
+typedoc --gitRevision <revision|branch|"{branch}">
 ```
 
-Has no effect if `--disableSources` is set.
-Use specified revision or branch instead of the last revision for linking to source files. Defaults to the last commit.
+Has no effect if `--disableSources` is set. Use specified revision or branch instead of the last revision for linking to
+source files. Defaults to the last commit. Accepts the special value `{branch}` to indicate that `{gitRevision}` in
+`sourceLinkTemplate` should be set to the current commit branch. If `gitRevision` is set to `{branch}` and the current
+HEAD is not set to the tip of a branch, TypeDoc will use the last commit instead.
 
 ## gitRemote
 

src/lib/converter/utils/repository.ts

@@ -125,6 +125,9 @@ export class GitRepository implements Repository {
  gitRemote: string,
  logger: Logger,
  ): GitRepository | undefined {
+ if (gitRevision === "{branch}") {
+ gitRevision = git("-C", path, "branch", "--show-current").stdout.trim();
+ }
  gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
  if (gitRevision == "HEAD") return; // Will only happen in a repo with no commits.
 

src/test/Repository.test.ts

@@ -155,6 +155,16 @@ describe("Repository", function () {
  repo.getURL(normalizePath(join(project.cwd, "test.js")), 1),
  "b53cc55bcdd9bc5920787a1d4a4a15fa24123b04/b53cc55b/test.js/1",
  );
+
+ const repo2 = GitRepository.tryCreateRepository(
+ project.cwd,
+ "{gitRevision}/{gitRevision:short}/{path}/{line}",
+ "{branch}", // revision
+ "origin", // remote
+ new TestLogger(),
+ );
+
+ equal(repo2?.gitRevision, "test");
  });
  });
 });