add dedicated page for commits key on content source; recommend setting...

** xref:content-branches.adoc[]

** xref:content-worktrees.adoc[]

** xref:content-tags.adoc[]

** xref:content-commits.adoc[]

** xref:content-source-start-path.adoc[]

** xref:content-source-start-paths.adoc[]

** xref:content-source-version.adoc[]

= Commits

Much like the `tags` key, the `commits` key can be used to target a fixed location in the repository.

The `commits` key accepts a list of exact commit hashes (or abbreviated hashes).

[#commits-key]

== commits key

The `commits` key is optional and can be specified directly on the `content` key or on a `url` key.

It accepts a single commit SHA1 hash or a list of hashes (e.g., `1a78ca8b0c543fb47dbbb689791f2e3986f1c588`).

The hashes may be abbreviated as permitted by git (e.g., `1a78ca8b`).

.antora-playbook.yml

[,yaml]

----

content:

  sources:

  - url: https://git-service.com/org/repo-y.git

    branches: ~

    commits: [1a78ca8b0c543fb47dbbb689791f2e3986f1c588] # <.>

  - url: https://git-service.com/org/repo-z.git

    branches: ~

    commits: c543fb47 # <.>

----

<.> Enclose multiple values in a set of square brackets (`+[]+`).

Separate each value with a comma (`,`).

<.> A single value is permitted.

The value may be an abbreviated commit.

WARNING: Setting the `commits` key does not automatically disable the xref:content-branches.adoc#default[default branches filter]!

After initially cloning the repository, Antora will go back to the repository and fetch commits until it finds all commits specified.

The relative depth of each fetch is controlled by the xref:git-fetch-depth.adoc[git.fetch_depth] key.

If you want Antora to fetch in batches, you are strongly recommended to set the value of this key greater than the default value of `1`.

If you do use tags, we recommend using dedicated documentation tags rather than reusing tags for software releases.

You can read more about our philosophy regarding documentation versioning on the xref:ROOT:content-source-versioning-methods.adoc[] page.

TIP: When writing an Antora extension, it's possible to specify one or more commits as an alternative to tags.

TIP: As an alternative to tags (i.e., named commits), it's possible to specify one or more commits.

The `commits` property on the content source accepts a String or String array of commit hashes.

If a commit is specified, it is required to be present in the repository.

If a commit is specified, it's required to be present in the repository.

[#tags-key]

== tags key

  fetch_depth: 10

----

TIP: If you are using a commit as a content source, you're strongly encouraged to increase the value of this key from the default of `1`.

Otherwise, Antora will fetch one commit at a time until it finds the specified commit.

If you want Antora to fetch the full history, set the value of this key to `0`.

.antora-playbook.yml