docs: add docs for the git functions

aminya · May 9, 2023 · d4906ce · d4906ce
1 parent c20f71a
commit d4906ce
Showing 1 changed file with 184 additions and 115 deletions.
diff --git a/src/Git.cmake b/src/Git.cmake
@@ -1,19 +1,135 @@
 include_guard()
 
-# Parse the given Git url into its components
-#
-# It expects the url to be in the form of:
-# `[protocol://][host]/user/repo[.git]`
-#
-# Input variables:
-# - INPUT_URL: The url to parse
-#
-# Output variables:
-# - PROTOCOL: The protocol of the url (http, https, ssh, etc)
-# - HOST: The host of the url (github, gitlab, etc)
-# - USER: The user of the url (username, organization, etc)
-# - REPOSITORY_NAME: The repository of the url (project name)
-# - FULL_URL: The url of the repository (protocol + host + user + repo)
+#[[.rst:
+
+``git_clone``
+===============
+
+Clone the given repository to the given path
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+- ``REMOTE_URL``: The url of the remote to add
+- ``REMOTE_NAME``: The name of the remote to add (defaults to the remote user)
+
+]]
+function(git_clone)
+  set(oneValueArgs REPOSITORY_PATH REMOTE_URL REMOTE_NAME)
+  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
+
+  if("${_fun_REPOSITORY_PATH}" STREQUAL "" OR "${_fun_REMOTE_URL}" STREQUAL "")
+    message(FATAL_ERROR "REPOSITORY_PATH and _fun_REMOTE_URL are required")
+  endif()
+
+  if(NOT EXISTS "${_fun_REPOSITORY_PATH}")
+    message(STATUS "Cloning at ${_fun_REPOSITORY_PATH}")
+
+    find_program(GIT_EXECUTABLE "git" REQUIRED)
+    get_filename_component(_fun_REPOSITORY_PARENT_PATH "${_fun_REPOSITORY_PATH}" DIRECTORY)
+    execute_process(
+      COMMAND "${GIT_EXECUTABLE}" "clone" "${_fun_REMOTE_URL}"
+      WORKING_DIRECTORY "${_fun_REPOSITORY_PARENT_PATH}" COMMAND_ERROR_IS_FATAL LAST
+    )
+  else()
+    message(STATUS "Repository already exists at ${_fun_REPOSITORY_PATH}.")
+    git_add_remote(
+      REMOTE_URL
+      "${_fun_REMOTE_URL}"
+      REPOSITORY_PATH
+      "${_fun_REPOSITORY_PATH}"
+      REMOTE_NAME
+      "${_fun_REMOTE_NAME}"
+    )
+  endif()
+endfunction()
+
+#[[.rst:
+
+``git_pull``
+============
+
+Pull the given repository
+
+It will temporarily switch back to the previous branch if the head is detached for updating
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+
+]]
+function(git_pull)
+  set(oneValueArgs REPOSITORY_PATH)
+  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
+
+  if("${_fun_REPOSITORY_PATH}" STREQUAL "")
+    message(FATAL_ERROR "REPOSITORY_PATH is required")
+  endif()
+
+  # store the current revision
+  git_revision(REVISION REPOSITORY_PATH "${_fun_REPOSITORY_PATH}")
+
+  git_switch_back(REPOSITORY_PATH "${_fun_REPOSITORY_PATH}")
+
+  message(STATUS "Updating ${_fun_REPOSITORY_PATH}")
+  find_program(GIT_EXECUTABLE "git" REQUIRED)
+  execute_process(COMMAND "${GIT_EXECUTABLE}" "pull" WORKING_DIRECTORY "${_fun_REPOSITORY_PATH}")
+
+  # restore the revision
+  git_checkout(REPOSITORY_PATH "${_fun_REPOSITORY_PATH}" REVISION "${REVISION}")
+endfunction()
+
+#[[.rst:
+
+``git_checkout``
+==================
+
+Checkout the given revision
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+- ``REVISION``: The revision to checkout
+
+]]
+function(git_checkout)
+  set(oneValueArgs REPOSITORY_PATH REVISION)
+  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
+
+  if("${_fun_REPOSITORY_PATH}" STREQUAL "" OR "${_fun_REVISION}" STREQUAL "")
+    message(FATAL_ERROR "REPOSITORY_PATH and REVISION are required")
+  endif()
+
+  find_program(GIT_EXECUTABLE "git" REQUIRED)
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" "-c" "advice.detachedHead=false" "checkout" "${_fun_REVISION}"
+    WORKING_DIRECTORY "${_fun_REPOSITORY_PATH}" COMMAND_ERROR_IS_FATAL LAST
+  )
+endfunction()
+
+#[[.rst:
+
+``git_parse_url``
+====================
+
+Parse the given Git url into its components
+
+It expects the url to be in the form of:
+`[protocol://][host]/user/repo[.git]`
+
+Input variables:
+
+- ``INPUT_URL``: The url to parse
+
+Output variables:
+
+- ``PROTOCOL``: The protocol of the url (http, https, ssh, etc)
+- ``HOST``: The host of the url (github, gitlab, etc)
+- ``USER``: The user of the url (username, organization, etc)
+- ``REPOSITORY_NAME``: The repository of the url (project name)
+- ``FULL_URL``: The url of the repository (protocol + host + user + repo)
+
+#]]
 function(
   git_parse_url
   INPUT_URL
@@ -61,12 +177,20 @@ function(
   set(${FULL_URL} ${_FULL_URL} PARENT_SCOPE)
 endfunction()
 
-# Add a remote to the given repository on the given path
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-# - REMOTE_URL: The url of the remote to add
-# - REMOTE_NAME: The name of the remote to add (defaults to the remote user)
+#[[.rst:
+
+``git_add_remote``
+=====================
+
+Add a remote to the given repository on the given path
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+- ``REMOTE_URL``: The url of the remote to add
+- ``REMOTE_NAME``: The name of the remote to add (defaults to the remote user)
+
+]]
 function(git_add_remote)
   set(oneValueArgs REPOSITORY_PATH REMOTE_URL REMOTE_NAME)
   cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
@@ -111,48 +235,22 @@ function(git_add_remote)
   endif()
 endfunction()
 
-# Clone the given repository to the given path
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-# - REMOTE_URL: The url of the remote to add
-# - REMOTE_NAME: The name of the remote to add (defaults to the remote user)
-function(git_clone)
-  set(oneValueArgs REPOSITORY_PATH REMOTE_URL REMOTE_NAME)
-  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
+#[[.rst:
 
-  if("${_fun_REPOSITORY_PATH}" STREQUAL "" OR "${_fun_REMOTE_URL}" STREQUAL "")
-    message(FATAL_ERROR "REPOSITORY_PATH and _fun_REMOTE_URL are required")
-  endif()
+``git_revision``
+================
 
-  if(NOT EXISTS "${_fun_REPOSITORY_PATH}")
-    message(STATUS "Cloning at ${_fun_REPOSITORY_PATH}")
+Find the current git revision of the given repository
 
-    find_program(GIT_EXECUTABLE "git" REQUIRED)
-    get_filename_component(_fun_REPOSITORY_PARENT_PATH "${_fun_REPOSITORY_PATH}" DIRECTORY)
-    execute_process(
-      COMMAND "${GIT_EXECUTABLE}" "clone" "${_fun_REMOTE_URL}"
-      WORKING_DIRECTORY "${_fun_REPOSITORY_PARENT_PATH}" COMMAND_ERROR_IS_FATAL LAST
-    )
-  else()
-    message(STATUS "Repository already exists at ${_fun_REPOSITORY_PATH}.")
-    git_add_remote(
-      REMOTE_URL
-      "${_fun_REMOTE_URL}"
-      REPOSITORY_PATH
-      "${_fun_REPOSITORY_PATH}"
-      REMOTE_NAME
-      "${_fun_REMOTE_NAME}"
-    )
-  endif()
-endfunction()
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+
+Output variables:
+
+- ``REVISION``: The variable to store the revision in
 
-# Find the current git revision of the given repository
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-# Output variables:
-# - REVISION: The variable to store the revision in
+]]
 function(git_revision REVISION)
   set(oneValueArgs REPOSITORY_PATH)
   cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
@@ -171,12 +269,22 @@ function(git_revision REVISION)
   set(${REVISION} ${_git_revision} PARENT_SCOPE)
 endfunction()
 
-# Check if the given repository is in a detached state
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-# Output variables:
-# - IS_DETACHED: The variable to store the result in
+#[[.rst:
+
+``git_is_detached``
+===================
+
+Check if the given repository is in a detached state
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+
+Output variables:
+
+- ``IS_DETACHED``: The variable to store the result in
+
+]]
 function(git_is_detached IS_DETACHED)
   set(oneValueArgs REPOSITORY_PATH)
   cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
@@ -200,10 +308,18 @@ function(git_is_detached IS_DETACHED)
   endif()
 endfunction()
 
-# Detect if the head is detached, if so, switch back before calling git pull on a detached head
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
+#[[.rst:
+
+``git_switch_back``
+===================
+
+Detect if the head is detached, if so, switch back before calling git pull on a detached head
+
+Input variables:
+
+- ``REPOSITORY_PATH``: The path to the repository
+
+]]
 function(git_switch_back)
   set(oneValueArgs REPOSITORY_PATH)
   cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
@@ -221,50 +337,3 @@ function(git_switch_back)
     )
   endif()
 endfunction()
-
-# Pull the given repository
-#
-# It will switch back to the previous branch if the head is detached for updating
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-function(git_pull)
-  set(oneValueArgs REPOSITORY_PATH)
-  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
-
-  if("${_fun_REPOSITORY_PATH}" STREQUAL "")
-    message(FATAL_ERROR "REPOSITORY_PATH is required")
-  endif()
-
-  # store the current revision
-  git_revision(REVISION REPOSITORY_PATH "${_fun_REPOSITORY_PATH}")
-
-  git_switch_back(REPOSITORY_PATH "${_fun_REPOSITORY_PATH}")
-
-  message(STATUS "Updating ${_fun_REPOSITORY_PATH}")
-  find_program(GIT_EXECUTABLE "git" REQUIRED)
-  execute_process(COMMAND "${GIT_EXECUTABLE}" "pull" WORKING_DIRECTORY "${_fun_REPOSITORY_PATH}")
-
-  # restore the revision
-  git_checkout(REPOSITORY_PATH "${_fun_REPOSITORY_PATH}" REVISION "${REVISION}")
-endfunction()
-
-# Checkout the given revision
-#
-# Input variables:
-# - REPOSITORY_PATH: The path to the repository
-# - REVISION: The revision to checkout
-function(git_checkout)
-  set(oneValueArgs REPOSITORY_PATH REVISION)
-  cmake_parse_arguments(_fun "" "${oneValueArgs}" "" ${ARGN})
-
-  if("${_fun_REPOSITORY_PATH}" STREQUAL "" OR "${_fun_REVISION}" STREQUAL "")
-    message(FATAL_ERROR "REPOSITORY_PATH and REVISION are required")
-  endif()
-
-  find_program(GIT_EXECUTABLE "git" REQUIRED)
-  execute_process(
-    COMMAND "${GIT_EXECUTABLE}" "-c" "advice.detachedHead=false" "checkout" "${_fun_REVISION}"
-    WORKING_DIRECTORY "${_fun_REPOSITORY_PATH}" COMMAND_ERROR_IS_FATAL LAST
-  )
-endfunction()