[Bug] The `branch:` lines in metadata show the branch name, but they should be commit IDs
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 11m
- Merged PRs (30d)
- 10
Description
When running `docfx metadata`, the resulting .yaml files have entries that include `branch: main` in their `source` sections:
```yaml
source:
remote:
path: src/xunit.v3.core/AssemblyFixtureAttribute.cs
branch: main
repo: https://github.com/xunit/xunit
id: AssemblyFixtureAttribute
path: ../src/xunit.v3.core/AssemblyFixtureAttribute.cs
startLine: 16
```
When generating documentation, the source links in the docs then point to the `main` branch source file rather than a permalink to the file that was used to build the documentation.
I expect these `branch:` entries to use the Git commit ID so that generated links are permanent.
Looking at [GitUtility](https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/Git/GitUtility.cs) I cannot simply override with a single environment variable, because my source uses Git submodules.
The only way to "fix" this today is a massive manual search and replace that is cognizant of which repo should get which commit ID. (Alternatively, if I run `docfx metadata` locally, outside of a CI environment, the generation is broken in a different way: it gets the `branch:` entries correct for the primary repo, but for some reason stops providing remote source information for the submodules, and includes broken local paths like `C:\Dev\...` instead of the relative paths like seen above. This leaves me with the search & replace as the only available mechanism.)
Is there a way to just tell `docfx metadata` that I would prefer commit IDs, and have it also track properly into Git submodules? I have not found an obvious switch or config option.
As an example of how I expect the metadata to appear, compare:
[https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.AssemblyFixtureAttribute.yml#L125-L132](https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.AssemblyFixtureAttribute.yml#L125-L132) (primary repo)
```yaml
source:
remote:
path: src/xunit.v3.core/AssemblyFixtureAttribute.cs
branch: ccd27e9792077b9ee82f40320c6f414e6a0338de
repo: https://github.com/xunit/xunit
id: .ctor
path: ../src/xunit.v3.core/AssemblyFixtureAttribute.cs
startLine: 16
```
[https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.Assert.yml#L333-L340](https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.Assert.yml#L333-L340) (submodule)
```yaml
source:
remote:
path: Assert.cs
branch: 892ce2e9656c2424790b1cd3a209e9d42882e62d
repo: https://github.com/xunit/assert.xunit
id: .ctor
path: ../src/xunit.v3.assert/Asserts/Assert.cs
startLine: 28
```
You can see the generated content with appropriate external links:
https://api.xunit.net/v3/2.0.2/v3.2.0.2-Xunit.AssemblyFixtureAttribute.-ctor.html#v3_2_0_2_Xunit_AssemblyFixtureAttribute__ctor_System_Type_
https://api.xunit.net/v3/2.0.2/v3.2.0.2-Xunit.Assert.-ctor.html
Contributor guide
Assessment
This issue has not been assessed yet.