name: vcs_tag
returns: custom_tgt
description: |
  This command detects revision control commit information at build time
  and places it in the specified output file. This file is guaranteed to
  be up to date on every build. Keywords are similar to [[custom_target]].

  Meson will read the contents of `input`, substitute the
  `replace_string` with the detected revision number, and write the
  result to `output`. This method returns a
  [[@custom_tgt]] object that (as usual) should be
  used to signal dependencies if other targets use the file outputted
  by this.

  For example, if you generate a header with this and want to use that
  in a build target, you must add the return value to the sources of
  that build target. Without that, Meson will not know the order in
  which to build the targets.

  If you desire more specific behavior than what this command provides,
  you should use [[custom_target]].

kwargs:
  command:
    type: array[exe | external_program | custom_tgt | file | str]
    description: |
      The command to execute, see [[custom_target]] for details
      on how this command must be specified.

      This parameter is optional. If it is absent, Meson will try
      its best to find a suitable default command.

      *(since 0.62.0)* [[@file]] is accepted.

      *(since 0.63.0)* [[@custom_tgt]], [[@exe]], and [[@external_program]] are accepted.

  input:
    type: str
    required: true
    description: File to modify (e.g. `version.c.in`).

  output:
    type: str
    required: true
    description: File to write the results to (e.g. `version.c`).

  fallback:
    type: str
    default: "[[meson.project_version]]"
    description: |
      Version number to use when no revision control information is present,
      such as when building from a release tarball.

  replace_string:
    type: str
    default: "'@VCS_TAG@'"
    description: String in the input file to substitute with the commit information.

  install:
    type: bool
    default: false
    since: 1.7.0
    description: |
      When true, this generated file is installed during
      the install step, and `install_dir` must be set and not empty.

  install_dir:
    type: str
    since: 1.7.0
    description: |
      The subdirectory to install the generated file to (e.g. `share/myproject`).

  install_mode:
    type: array[str | int]
    since: 1.7.0
    description: |
      Specify the file mode in symbolic format
      and optionally the owner/uid and group/gid for the installed files.

      See the `install_mode` kwarg of [[install_data]] for more information.

  install_tag:
    type: str
    since: 1.7.0
    description: |
      A string used by the `meson install --tags` command
      to install only a subset of the files. By default the file has no install
      tag which means it is not being installed when `--tags` argument is specified.