FindGit: Add Git_VERSION

This deprecates the GIT_VERSION_STRING result variable. Issue: #27088 Fixes: #26868
2025-10-14 02:08:27 +08:00 · 2025-09-14 21:08:16 +02:00
parent dd06fad849
commit fe72a5dba2
10 changed files with 58 additions and 33 deletions
--- a/Help/release/dev/find-modules.rst
+++ b/Help/release/dev/find-modules.rst
@@ -28,6 +28,9 @@ Find Modules
 * The :module:`FindGettext` module now provides a ``Gettext_VERSION`` result
  variable.  The ``GETTEXT_VERSION_STRING`` result variable is deprecated.

+* The :module:`FindGit` module now provides a ``Git_VERSION`` result
+  variable.  The ``GIT_VERSION_STRING`` result variable is deprecated.
+
 * The :module:`FindGnuplot` module now provides a ``Gnuplot_VERSION`` result
  variable.  The ``GNUPLOT_VERSION_STRING`` result variable is deprecated.

--- a/Modules/ExternalProject/shared_internal_commands.cmake
+++ b/Modules/ExternalProject/shared_internal_commands.cmake
@@ -55,9 +55,9 @@ function(_ep_get_git_remote_url output_variable working_directory)
    endif()
  endif()

-  if(GIT_VERSION VERSION_LESS 1.7.5)
+  if(Git_VERSION VERSION_LESS 1.7.5)
    set(_git_remote_url_cmd_args config remote.${git_remote_name}.url)
-  elseif(GIT_VERSION VERSION_LESS 2.7)
+  elseif(Git_VERSION VERSION_LESS 2.7)
    set(_git_remote_url_cmd_args ls-remote --get-url ${git_remote_name})
  else()
    set(_git_remote_url_cmd_args remote get-url ${git_remote_name})
@@ -399,7 +399,7 @@ function(_ep_write_gitclone_script
  tls_verify
 )

-  if(NOT GIT_VERSION_STRING VERSION_LESS 1.8.5)
+  if(NOT Git_VERSION VERSION_LESS 1.8.5)
    # Use `git checkout <tree-ish> --` to avoid ambiguity with a local path.
    set(git_checkout_explicit-- "--")
  else()
@@ -412,14 +412,14 @@ function(_ep_write_gitclone_script
    message(FATAL_ERROR "Tag for git checkout should not be empty.")
  endif()

-  if(GIT_VERSION_STRING VERSION_LESS 2.20 OR
-    2.21 VERSION_LESS_EQUAL GIT_VERSION_STRING)
+  if(Git_VERSION VERSION_LESS 2.20 OR
+    2.21 VERSION_LESS_EQUAL Git_VERSION)
    set(git_clone_options "--no-checkout")
  else()
    set(git_clone_options)
  endif()
  if(git_shallow)
-    if(NOT GIT_VERSION_STRING VERSION_LESS 1.7.10)
+    if(NOT Git_VERSION VERSION_LESS 1.7.10)
      list(APPEND git_clone_options "--depth 1 --no-single-branch")
    else()
      list(APPEND git_clone_options "--depth 1")
@@ -511,10 +511,10 @@ function(_ep_write_gitupdate_script
    message(FATAL_ERROR "Tag for git checkout should not be empty.")
  endif()
  set(git_stash_save_options --quiet)
-  if(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.7)
+  if(Git_VERSION VERSION_GREATER_EQUAL 1.7.7)
    # This avoids stashing files covered by .gitignore
    list(APPEND git_stash_save_options --include-untracked)
-  elseif(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.6)
+  elseif(Git_VERSION VERSION_GREATER_EQUAL 1.7.6)
    # Untracked files, but also ignored files, so potentially slower
    list(APPEND git_stash_save_options --all)
  endif()
@@ -740,10 +740,10 @@ function(_ep_get_git_submodules_recurse git_submodules_recurse)
  set(${git_submodules_recurse} "${recurseFlag}" PARENT_SCOPE)

  # The git submodule update '--recursive' flag requires git >= v1.6.5
-  if(recurseFlag AND GIT_VERSION_STRING VERSION_LESS 1.6.5)
+  if(recurseFlag AND Git_VERSION VERSION_LESS 1.6.5)
    message(FATAL_ERROR
      "git version 1.6.5 or later required for --recursive flag with "
-      "'git submodule ...': GIT_VERSION_STRING='${GIT_VERSION_STRING}'"
+      "'git submodule ...': Git_VERSION='${Git_VERSION}'"
    )
  endif()
 endfunction()
@@ -921,7 +921,7 @@ function(_ep_add_download_command name)
  elseif(git_repository)
    set(method git)
    # FetchContent gives us these directly, so don't try to recompute them
-    if(NOT GIT_EXECUTABLE OR NOT GIT_VERSION_STRING)
+    if(NOT GIT_EXECUTABLE OR NOT Git_VERSION)
      unset(CMAKE_MODULE_PATH) # Use CMake builtin find module
      find_package(Git QUIET)
      if(NOT GIT_EXECUTABLE)
@@ -957,7 +957,7 @@ function(_ep_add_download_command name)

    # If git supports it, make checkouts quiet when checking out a git hash.
    # This avoids the very noisy detached head message.
-    if(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.7)
+    if(Git_VERSION VERSION_GREATER_EQUAL 1.7.7)
      list(PREPEND git_config advice.detachedHead=false)
    endif()

@@ -1496,7 +1496,7 @@ function(_ep_add_update_command name)

  elseif(git_repository)
    # FetchContent gives us these directly, so don't try to recompute them
-    if(NOT GIT_EXECUTABLE OR NOT GIT_VERSION_STRING)
+    if(NOT GIT_EXECUTABLE OR NOT Git_VERSION)
      unset(CMAKE_MODULE_PATH) # Use CMake builtin find module
      find_package(Git QUIET)
      if(NOT GIT_EXECUTABLE)
--- a/Modules/FetchContent.cmake
+++ b/Modules/FetchContent.cmake
@@ -1886,9 +1886,9 @@ ExternalProject_Add_Step(${contentName}-populate copyfile
 # Pass through things we've already detected in the main project to avoid
 # paying the cost of redetecting them again in ExternalProject_Add()
 set(GIT_EXECUTABLE [==[${GIT_EXECUTABLE}]==])
-set(GIT_VERSION_STRING [==[${GIT_VERSION_STRING}]==])
+set(Git_VERSION [==[${Git_VERSION}]==])
 set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION
-  [==[${GIT_EXECUTABLE};${GIT_VERSION_STRING}]==]
+  [==[${GIT_EXECUTABLE};${Git_VERSION}]==]
 )
 ")
  endif()
--- a/Modules/FindGit.cmake
+++ b/Modules/FindGit.cmake
@@ -31,9 +31,13 @@ Result Variables
 This module defines the following variables:

 ``Git_FOUND``
-  Boolean indicating whether the Git was found.  For backward compatibility, the
-  ``GIT_FOUND`` variable is also set to the same value.
-``GIT_VERSION_STRING``
+  Boolean indicating whether (the requested version of) Git was found.  For
+  backward compatibility, the ``GIT_FOUND`` variable is also set to the same
+  value.
+
+``Git_VERSION``
+  .. versionadded:: 4.2
+
  The version of Git found.

 Cache Variables
@@ -44,6 +48,17 @@ The following cache variables may also be set:
 ``GIT_EXECUTABLE``
  Path to the ``git`` command-line client executable.

+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``GIT_VERSION_STRING``
+  .. deprecated:: 4.2
+    Use ``Git_VERSION``, which has the same value.
+
+  The version of Git found.
+
 Examples
 ^^^^^^^^

@@ -128,7 +143,8 @@ if(GIT_EXECUTABLE)
    list(GET __gitVersionProp 0 __gitExe)
    list(GET __gitVersionProp 1 __gitVersion)
    if(__gitExe STREQUAL GIT_EXECUTABLE AND NOT __gitVersion STREQUAL "")
-      set(GIT_VERSION_STRING "${__gitVersion}")
+      set(Git_VERSION "${__gitVersion}")
+      set(GIT_VERSION_STRING "${Git_VERSION}")
      set(__doGitVersionCheck FALSE)
    endif()
    unset(__gitExe)
@@ -142,9 +158,10 @@ if(GIT_EXECUTABLE)
                    ERROR_QUIET
                    OUTPUT_STRIP_TRAILING_WHITESPACE)
    if (git_version MATCHES "^git version [0-9]")
-      string(REPLACE "git version " "" GIT_VERSION_STRING "${git_version}")
+      string(REPLACE "git version " "" Git_VERSION "${git_version}")
+      set(GIT_VERSION_STRING "${Git_VERSION}")
      set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION
-        "${GIT_EXECUTABLE};${GIT_VERSION_STRING}"
+        "${GIT_EXECUTABLE};${Git_VERSION}"
      )
    endif()
    unset(git_version)
@@ -162,4 +179,4 @@ endif()
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(Git
                                  REQUIRED_VARS GIT_EXECUTABLE
-                                  VERSION_VAR GIT_VERSION_STRING)
+                                  VERSION_VAR Git_VERSION)
--- a/Tests/CMakeOnly/AllFindModules/CMakeLists.txt
+++ b/Tests/CMakeOnly/AllFindModules/CMakeLists.txt
@@ -120,7 +120,7 @@ foreach(
    DevIL Doxygen DOXYGEN
    EXPAT
    FLEX Freetype
-    Gettext GIF GnuTLS GNUTLS GTK2
+    Gettext GIF Git GnuTLS GNUTLS GTK2
    HDF5 Hg HSPELL
    Icotool
    Jasper JPEG
--- a/Tests/ExternalProject/CMakeLists.txt
+++ b/Tests/ExternalProject/CMakeLists.txt
@@ -35,8 +35,8 @@ if(NOT DEFINED EP_TEST_GIT OR EP_TEST_GIT)
  find_package(Git)
 endif()
 if(NOT DEFINED EP_TEST_GIT AND Git_FOUND)
-  message(STATUS "GIT_VERSION_STRING='${GIT_VERSION_STRING}'")
-  if(NOT "${GIT_VERSION_STRING}" VERSION_LESS 1.6.5)
+  message(STATUS "Git_VERSION='${Git_VERSION}'")
+  if(NOT Git_VERSION VERSION_LESS 1.6.5)
    set(EP_TEST_GIT 1)
  endif()
 endif()
@@ -373,7 +373,7 @@ if(EP_TEST_GIT)
  # Live git / master (no GIT_TAG), but git config flags
  #
  # The `git clone --config` parameter has been introduced in Git 1.7.7
-  if(NOT git_version VERSION_LESS 1.7.7)
+  if(NOT Git_VERSION VERSION_LESS 1.7.7)
    set(proj TutorialStep1-GIT-config)
    ExternalProject_Add(${proj}
      GIT_REPOSITORY "${local_git_repo}"
@@ -658,7 +658,7 @@ if(EP_TEST_GIT)
  add_test(TutorialStep1-GIT-master
    ${CMAKE_COMMAND} -P "${binary_base}/TutorialStep1-GIT-master/example.cmake")

-  if(NOT git_version VERSION_LESS 1.7.7)
+  if(NOT Git_VERSION VERSION_LESS 1.7.7)
    add_test(TutorialStep1-GIT-config
      ${CMAKE_COMMAND} -P "${binary_base}/TutorialStep1-GIT-config/example.cmake")
  endif()
--- a/Tests/ExternalProjectUpdate/CMakeLists.txt
+++ b/Tests/ExternalProjectUpdate/CMakeLists.txt
@@ -56,9 +56,9 @@ set(do_git_tests 0)
 if(GIT_EXECUTABLE)
  set(do_git_tests 1)

-  message(STATUS "GIT_VERSION_STRING='${GIT_VERSION_STRING}'")
+  message(STATUS "Git_VERSION='${Git_VERSION}'")

-  if("${GIT_VERSION_STRING}" VERSION_LESS 1.6.5)
+  if(Git_VERSION VERSION_LESS 1.6.5)
    message(STATUS "No ExternalProject git tests with git client less than version 1.6.5")
    set(do_git_tests 0)
  endif()
--- a/Tests/ExternalProjectUpdate/ExternalProjectUpdateTest.cmake
+++ b/Tests/ExternalProjectUpdate/ExternalProjectUpdateTest.cmake
@@ -177,9 +177,9 @@ set(do_git_tests 0)
 if(GIT_EXECUTABLE)
  set(do_git_tests 1)

-  message(STATUS "GIT_VERSION_STRING='${GIT_VERSION_STRING}'")
+  message(STATUS "Git_VERSION='${Git_VERSION}'")

-  if("${GIT_VERSION_STRING}" VERSION_LESS 1.6.5)
+  if(Git_VERSION VERSION_LESS 1.6.5)
    message(STATUS "No ExternalProject git tests with git client less than version 1.6.5")
    set(do_git_tests 0)
  endif()
--- a/Tests/FindGit/Test/CMakeLists.txt
+++ b/Tests/FindGit/Test/CMakeLists.txt
@@ -8,6 +8,7 @@ add_test(NAME test_git
  COMMAND ${CMAKE_COMMAND}
  "-DGIT_EXECUTABLE=${GIT_EXECUTABLE}"
  "-DGIT_EXECUTABLE_TARGET=$<TARGET_FILE:Git::Git>"
+  "-DGit_VERSION=${Git_VERSION}"
  "-DGIT_VERSION_STRING=${GIT_VERSION_STRING}"
  -P "${CMAKE_CURRENT_LIST_DIR}/RunGit.cmake"
  )
--- a/Tests/FindGit/Test/RunGit.cmake
+++ b/Tests/FindGit/Test/RunGit.cmake
@@ -11,8 +11,12 @@ function(run_git exe exe_display)
    message(SEND_ERROR "Result of ${exe_display} --version is ${result}, should be 0")
  endif()

-  if(NOT output STREQUAL "git version ${GIT_VERSION_STRING}")
-    message(SEND_ERROR "Output of ${exe_display} --version is \"${output}\", should be \"git version ${GIT_VERSION_STRING}\"")
+  if(NOT output STREQUAL "git version ${Git_VERSION}")
+    message(SEND_ERROR "Output of ${exe_display} --version is \"${output}\", should be \"git version ${Git_VERSION}\"")
+  endif()
+
+  if(NOT Git_VERSION VERSION_EQUAL GIT_VERSION_STRING)
+    message(SEND_ERROR "Git_VERSION=\"${Git_VERSION}\" is not equal to GIT_VERSION_STRING=\"${GIT_VERSION_STRING}\"")
  endif()
 endfunction()