XS✔ ◾ Fetch Depth Docs

README.md

@@ -148,6 +148,26 @@ when using this trigger.**
 Instructions on using the action within Azure Pipelines can be found
 [here][azurepipelinestask].
 
+## Git History
+
+If your repository contains _any_ non-linear history, it will be necessary to
+fetch Git history during checkout. This can be done by updating the
+`actions/checkout` step:
+
+```YAML
+- uses: actions/[email protected]
+  fetch-depth: 0
+```
+
+In many cases, `fetch-depth` will not be required so it is recommended not to
+set this unless the action explicitly requests it. It may also be possible to
+set this to a value greater than 0 if you only require a partial history, but it
+can be difficult to determine a value that will work consistently, due to the
+nature of Git history.
+
+To avoid this, it is recommended to only use commit types that squash the Git
+history such as "squash merge" or "rebase and fast-forward".
+
 ## Troubleshooting
 
 A set of steps for troubleshooting any issues encountered can be found

docs/azure-pipelines-task.md

@@ -94,17 +94,38 @@ You can use a name other than `PR_Metrics_Access_Token` if you wish, but you
 will need to keep the name unified across the variable and task definitions. The
 name `PR_METRICS_ACCESS_TOKEN` cannot be altered.
 
-## Always Close Comment
+## Git History
+
+If your repository contains _any_ non-linear history, it will be necessary to
+fetch Git history during checkout. This can be done by updating the `checkout`
+step:
+
+```YAML
+- checkout: self
+  fetchDepth: 0
+```
 
-The `AlwaysCloseComment` option is not available for GitHub PRs as the main size
-and test comment there cannot be open by default.
+Alternatively, if using classic pipelines, you can disable 'Shallow fetch' under
+the build process phase settings.
+
+In many cases, `fetchDepth` will not be required so it is recommended not to set
+this unless the task explicitly requests it. It may also be possible to set this
+to a value greater than 0 if you only require a partial history, but it can be
+difficult to determine a value that will work consistently, due to the nature of
+Git history.
+
+To avoid this, it is recommended to only use commit types that squash the Git
+history such as ["squash merge" or "rebase and fast-forward"][squashmerge].
+
+## Always Close Comment
 
-By default in Azure DevOps, the comment is left open if it requires further
-attention, such as when a smaller PR or increased test coverage is suggested. If
-this input is set to `true`, the comment will be closed, to prevent it blocking
-automatic closure of the PR.
+By default, the comment is left open if it requires further attention, such as
+when a smaller PR or increased test coverage is suggested. If the
+`AlwaysCloseComment` option is set to `true`, the comment will be closed, to
+prevent it blocking automatic closure of the PR.
 
 [addingtask]: https://docs.microsoft.com/azure/devops/pipelines/customize-pipeline
 [workloadidentityfederation]: workload-identity-federation.md
 [githubpat]: https://docs.github.com/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
 [githubsecret]: https://docs.github.com/actions/reference/encrypted-secrets
+[squashmerge]: https://learn.microsoft.com/azure/devops/repos/git/merging-with-squash