From d4906ce391d5137e6b9a34b5044b93e5c48f55c7 Mon Sep 17 00:00:00 2001 From: Amin Yahyaabadi Date: Mon, 8 May 2023 20:34:37 -0700 Subject: [PATCH] docs: add docs for the git functions --- src/Git.cmake | 299 +++++++++++++++++++++++++++++++------------------- 1 file changed, 184 insertions(+), 115 deletions(-) diff --git a/src/Git.cmake b/src/Git.cmake index 5094093c..2ec753d8 100644 --- 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()