Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Usage Guide in Readme #46

Merged
merged 2 commits into from
Mar 26, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,56 @@ It also supports sparse checkout for checking out specific files from a large re
- 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`](./cmake/GitCheckout.cmake) file and include it in the CMake project.
- Use [`file(DOWNLOAD)`](https://cmake.org/cmake/help/latest/command/file.html#download) to automatically download the `GitCheckout.cmake` file.
- Use [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) to add this package to the CMake project.

## Example Usages

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

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

### Specify Output Directory

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

```cmake
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:

```cmake
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:

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

## License

This project is licensed under the terms of the [MIT License](./LICENSE).
Expand Down