FindGit: Add Git_VERSION

This deprecates the GIT_VERSION_STRING result variable.

Issue: #27088
Fixes: #26868

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.
 

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
+  if(Git_VERSION VERSION_LESS 2.20 OR
-    2.21 VERSION_LESS_EQUAL GIT_VERSION_STRING)
+    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)

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()

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
+  Boolean indicating whether (the requested version of) Git was found.  For
-  ``GIT_FOUND`` variable is also set to the same value.
+  backward compatibility, the ``GIT_FOUND`` variable is also set to the same
-``GIT_VERSION_STRING``
+  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)

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

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}'")
+  message(STATUS "Git_VERSION='${Git_VERSION}'")
-  if(NOT "${GIT_VERSION_STRING}" VERSION_LESS 1.6.5)
+  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()

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()

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()

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"
   )

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}")
+  if(NOT output STREQUAL "git version ${Git_VERSION}")
-    message(SEND_ERROR "Output of ${exe_display} --version is \"${output}\", should be \"git version ${GIT_VERSION_STRING}\"")
+    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()