threeal / git-checkout-cmake

Clone and check out a Git repository from a CMake project

GitCheckout.cmake

Clone and check out a Git repository from a CMake project.

This module contains a git_checkout function for cloning a Git repository from a remote location and checking out the files based on the given reference, which can be a commit hash, branch, or tag. It also supports sparse checkout for checking out specific files from a large repository.

Key Features

• Cloning a Git repository from a remote location.
• Checking out a Git repository on a specific reference.
• Support for sparse checkout.

Integration

This module can be integrated into a CMake project in the following ways:

• Manually download the GitCheckout.cmake file and include it in the CMake project:

  include(path/to/GitCheckout.cmake)

• Use file(DOWNLOAD) to automatically download the GitCheckout.cmake file:

  file(
    DOWNLOAD https://threeal.github.io/git-checkout-cmake/v1.1.0
    ${CMAKE_BINARY_DIR}/GitCheckout.cmake
  )
  include(${CMAKE_BINARY_DIR}/GitCheckout.cmake)

• Use CPM.cmake to add this package to the CMake project:

  cpmaddpackage(gh:threeal/[email protected])
  include(${GitCheckout_SOURCE_DIR}/cmake/GitCheckout.cmake)

Example Usages

This example demonstrates how to clone and check out a Git repository hosted on GitHub:

git_checkout("https://github.com/user/project")

Specify Output Directory

Use the DIRECTORY option to specify the output directory for cloning the Git repository:

git_checkout(
  "https://github.com/user/project"
  DIRECTORY path/to/output
)

Specify Checkout Reference

By default, a Git repository will be checked out on the default branch. To check out on a specific commit hash, branch, or tag, use the REF option:

git_checkout(
  "https://github.com/user/project"
  REF latest
)

Use Sparse Checkout

To save bandwidth, it is recommended to use a sparse checkout to check out only specific files from the Git repository, especially on a large repository. To do this, use the SPARSE_CHECKOUT option to list patterns of files to be checked out sparsely:

git_checkout(
  "https://github.com/user/project"
  SPARSE_CHECKOUT src test
)

License

This project is licensed under the terms of the MIT License.

Copyright © 2024 Alfi Maulana

git-checkout-cmake's Issues

Determine Git Output Directory If Given Relative Path

This issue suggests modifying the behavior of the git_checkout function to determine the Git output directory to be placed under the CMAKE_CURRENT_BINARY_DIR variable if the DIRECTORY argument is a relative path. This change is proposed to prevent the Git directory from being placed relative to the current process working directory, which can lead to inconsistency.

Add Support to Do Sparse Check Out

This issue suggests adding support in the git_checkout function to do sparse check out on a Git repository by specifying list of paths to check out using the SPARSE_CHECKOUT arguments.

Separate Steps for Git Clone and Check Out

This issue suggests modifying the behavior in the git_checkout function by separating the steps for Git clone and Git checkout. This means that Git clone should no longer check out a Git repository, which can be achieved by specifying the --no-checkout argument during the Git clone. Consequently, Git checkout should always be called separately to ensure that all files in the cloned repository are available.

This change is proposed to allow #17 to be implemented smoothly because sparse checkout requires Git clone to be performed without any checkout before specifying files to be sparsely checked out.

Add Git Directory Assertion For Testing

This issue suggests adding an assertion for testing named assert_git_directory to check if the given path is a directory and if it is a Git directory or not. To check if the given path is a Git directory, we can simply call git status to check the status of the Git directory at that path.

This change is proposed to provide a better assertion for testing and to separate the context for directory checks, which currently only exist in the assert_git_complete_checkout function.

Utilize CTest Action

This issue suggests using the CTest Action for running tests in the workflow, replacing the ctest command. Refer to threeal/cpp-starter#132 for more information and the rationale behind this suggestion.

Modify Git Complete Checkout Assertion to Optionally Assert Commit SHA

This issue suggests adding support to the assert_git_complete_checkout function to assert the commit SHA of the checked-out Git repository. This can be done by adding an optional EXPECTED_COMMIT_SHA argument for specifying the expected commit SHA of the checked-out Git repository.

Add Error Handling Function

This issue suggests separating the lines in the git_checkout function into a private function named _set_error.

git-checkout-cmake/cmake/GitCheckout.cmake

Lines 17 to 21 in 380c0be

	if(ARG_ERROR_VARIABLE)
	set(${ARG_ERROR_VARIABLE} "Failed to clone ${URL} (${RES})" PARENT_SCOPE)
	else()
	message(FATAL_ERROR "Failed to clone ${URL} (${RES})")
	endif()

The aim is to enable reusability of the error handling when marking a specific line of code in CMake as an error. Additionally, this separation aims to avoid specifying two error messages when the ERROR_VARIABLE is both defined and not defined.

Display Error for Existing Files or Directories in Git Clone Output Path

This issue suggests modifying the behavior of the git_clone function to display an error if a file or directory already exists in the Git clone output path. This modification is proposed to provide a clearer explanation for why the git_clone function is failing.

Add Function for Checking Valid Git Directory

This issue suggests adding a new _check_valid_git_directory function to check if the given path is a valid Git directory. This function will be useful in preventing duplication when checking for a valid Git directory in the _git_incomplete_clone and _assert_git_directory functions.

Remove Badges from Readme

This issue suggests removing badges from the README.md file because the information in the badges does not seem to be important to include in the readme. Refer to threeal/pipx-install-action#119 for more information and the rationale behind this proposal.

Utilize Find Git in Assertion

This issue suggests utilizing the _find_git function in the Assertion.cmake module to check if Git is available and obtain the valid Git executable.

Reorder Tests

This issue suggests reordering the following test lists to be ordered based on function dependencies:

git-checkout-cmake/test/CMakeLists.txt

Lines 13 to 33 in e867206

	add_cmake_test(
	GitCheckoutTest.cmake
	"Check out a Git repository"
	"Check out a Git repository to a specific directory"
	"Check out a Git repository on a specific ref"
	"Check out a Git repository on a specific invalid ref"
	"Check out a Git repository sparsely"
	)
	add_cmake_test(
	GitCloneTest.cmake
	"Incompletely clone a Git repository"
	"Incompletely clone an invalid Git repository"
	"Incompletely clone a Git repository to a specific directory"
	)
	add_cmake_test(
	SetErrorTest.cmake
	"Set error"
	"Set error with variable specified"
	)

Reordering by function dependency means that the tests for the _set_error function should be run before the tests for the _git_incomplete_clone and git_checkout functions, and so on.

Utilize Assertion.cmake

This issue suggests utilizing the Assertion.cmake module to simplify assertions during testing, replacing most functions from the Assertion.cmake module declared in this project.

Modify Git Incomplete Clone Function to Always Require Directory Argument

This issue suggests modifying the _git_incomplete_clone function to always require the DIRECTORY argument. This change is proposed because the _git_incomplete_clone is a private function, so having an optional argument in it seems unnecessary since the function will only be called internally, in this case, it is being called by the git_checkout function.

This change is proposed especially to prevent having the following lines for checking if the DIRECTORY argument is given duplicated in both the _git_incomplete_clone and git_checkout functions:

git-checkout-cmake/cmake/GitCheckout.cmake

Lines 32 to 35 in 78ad431

	if(NOT DEFINED ARG_DIRECTORY)
	# Determines the directory of the cloned Git repository if it is not specified.
	string(REGEX REPLACE ".*/" "" ARG_DIRECTORY ${URL})
	endif()

It is suggested to make the _git_incomplete_clone always require the DIRECTORY argument so that it does not need to handle the case if the DIRECTORY argument is not defined, letting the undefined DIRECTORY argument be handled by the git_checkout function instead.

Host Modules on GitHub Pages

This issue suggests hosting the latest GitCheckout.cmake module on the GitHub page. This change is proposed to shorten the URL required to download the GitCheckout.cmake from https://raw.githubusercontent.com/threeal/git-checkout-cmake/main/cmake/GitCheckout.cmake to https://threeal.github.io/git-checkout-cmake/latest. To achieve this, we may need to add a new job to retrieve the latest GitCheckout.cmake module and upload it for deployment on the GitHub Page.

Trigger Deploy Workflow on Push Tag Events

This issue suggests modifying the Deploy workflow to also be triggered by push tag events alongside push events to the main branch. Refer to threeal/assertion-cmake#32 for more information and the rationale behind this suggestion.

Remove Error Handling

This issue suggests removing the error handling implemented by passing an error variable in favor of using the default fatal error message. This change is suggested because having an error variable to pass an error between functions is overengineering for the requirement of this project. It is better to keep it simple by using a fatal error message if there's an error.

This will mean the user will not be able to recover if there's an error during checking out a Git repository, but we shouldn't worry too much about it for now. Error handling should only be implemented if there's a case that requires it in the future.

Add License Notice to Exported Files

This issue suggests adding a license notice at the top of each exported file with the following content:

This code is licensed under the terms of the MIT License.
Copyright (c) 2024 Alfi Maulana

Add Support to Check Out on a Specific Reference

This issue suggests adding support to check out a Git repository on a specific reference (branch, tag, or commit) by adding a REF argument to the git_checkout function.

Organize Test Modules in `test/cmake`

This issue suggests organizing the test modules into the test/cmake directory. Refer to threeal/cmake-starter#36 for more information and the rationale behind this suggestion.

Prepend New Entry of CMake Module Path

This issue suggests prepending a new entry of the CMake module path instead of appending it, prioritizing the new entry over the older ones.

Add Usage Guide in Readme

This issue suggests adding a usage guide on how to integrate this module into other CMake projects and how to use the git_checkout function to clone and check out a Git repository.

Separate Git Clone Function

This issue suggests separating the lines in the git_checkout function that handle the cloning step of a Git repository into a separate private function named _git_clone. This change is proposed to provide a clearer context for the cloning step of a Git repository, especially after adding more functionality like in #24.

It is also suggested to separate the testing accordingly.

Remove Minimum CMake Requirement in Assertion Module

This issue suggests removing the following line from the Assertion.cmake module:

git-checkout-cmake/test/cmake/Assertion.cmake

Line 3 in 634edb6

cmake_minimum_required(VERSION 3.3)

The line is proposed to be removed for the following reasons:

• CMake versions lower than 3.5 are essentially deprecated.
• By default, this project already requires CMake version 3.19, which is higher than the minimum version set in the Assertion.cmake module.

Add Function to Determine Git Directory

This issue suggests moving the following line into a separate internal function named _determine_git_directory:

git-checkout-cmake/cmake/GitCheckout.cmake

Lines 60 to 63 in 0fc2b02

	if(NOT DEFINED ARG_DIRECTORY)
	# Determines the directory of the cloned Git repository if it is not specified.
	string(REGEX REPLACE ".*/" "" ARG_DIRECTORY ${URL})
	endif()

This line is proposed to be moved into a separate function to allow it to be tested, ensuring the correctness of its behavior. This change will also be useful for implementing #77 since the behavior of the changes proposed by that issue will be testable.

Update Project Description in Readme

This issue suggests updating the README.md file to contain a better project description and key features of this module.

Improve Error Handling

This issue suggests improving error handling within this project by adding support for specifying an ERROR_VARIABLE argument when calling the git_checkout function. This argument would specify that an error should be passed to that variable instead of being printed as a fatal error. This change is proposed to provide flexible error handling in this project, allowing users to handle failures when calling the git_checkout function.

Fill Project Information From Template

This issue suggests filling the project information from template provided by the CMake Starter.

Prefix Test Command Names

This issue suggests prefixing test command names with test_. Refer to threeal/cmake-starter#48 for more information and the rationale behind this change.

Correctly Quote Expanded Variables

This issue suggests using quotation marks in most cases of expanded variables. Refer to threeal/cmake-starter#50 for more information and the rationale behind this suggestion.

Allow Check Out to Existing Git Directory

This issue suggests modifying the _git_incomplete_clone function to allow it to clone a Git repository to an existing path that contains a Git repository by ignoring it instead of throwing an error. In this case, this function is safe to be called multiple times to perform checkout on the same directory without first checking whether the directory already exists or not.

Add Function for Cloning and Checking Out Git Repository

This issue suggests adding a new git_checkout function for cloning and checking out a Git repository from a remote location. The function should be able to clone a repository using a URL to a specific directory.

Add Example Integration in CMake

This issue suggests expanding the "Integration" section in the README.md file by adding code examples in CMake on how to perform each mentioned integration.

Check If Git Checked Out Completely in Testing

This issue suggests adding more assertions in the testing to verify if a Git repository is checked out completely. This can be achieved by verifying that running a git diff command does not result in any differences. This change is proposed to ensure that all files are checked out when calling the git_checkout function, which is particularly useful for testing the implementation of #17.

Check Valid Git Directory by Comparing Top-Level Path

This issue suggests modifying how to check if a directory contains a Git repository by comparing the Git top-level path with the directory path. This change is proposed because merely checking the Git status or if a path is inside a Git directory is not sufficient. Since this project itself is within a Git repository, any directory or files within this project will be considered inside a Git directory. Therefore, comparing the top-level paths is a better approach to determine whether a directory contains a Git repository or not.

Add Support to Check Out on a Specific Directory

This issue suggests adding support in the git_clone function for specifying the output directory of the cloned repository by using the DIRECTORY argument.

Utilize FindGit to Check for Git Existence

This issue suggests utilizing FindGit to check whether Git exists or not in the system. This approach is suggested to provide a clear reason if the Git command fails due to the executable not existing.

Allow Spaces in Test Function Names

This issue suggests allowing spaces in the test function names, making the test functions clear by having the same name as the test name. Refer to threeal/cmake-starter#53 for more information and the rationale behind this change.

Refactor Tests to Be Declared as Functions

This issue suggests modifying the tests to be declared as functions. Refer to threeal/cmake-starter#46 for more information and the rationale behind this proposal.

Separate Tests for Each Function

This issue suggests separating tests in the GitCheckoutTest.cmake file into several files based on the function to test. This change is proposed to separate context in the test files, separating them before adding more tests in the future.

Add Function for Asserting Message

This issue suggests adding a function named assert_message for asserting a message called from the message function. It also suggests mocking the message function from the beginning but adding a switch for enabling or disabling the mocking. The mock should be disabled from the beginning.

Host All Module Versions on GitHub Pages

This issue suggests hosting all versions of the GitCheckout.cmake module on GitHub Pages instead of just the latest module. To achieve this, one can look into Git tags for all available versions of the GitCheckout.cmake module and copy each module accordingly.