Skip to content

Commit 4261e4b

Browse files
authored
docs: add usage guide in readme (#46)
* docs(readme): add example usages section * docs(readme): add integration section
1 parent 598a202 commit 4261e4b

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

README.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,56 @@ It also supports sparse checkout for checking out specific files from a large re
1111
- Checking out a Git repository on a specific reference.
1212
- Support for sparse checkout.
1313

14+
## Integration
15+
16+
This module can be integrated into a CMake project in the following ways:
17+
18+
- Manually download the [`GitCheckout.cmake`](./cmake/GitCheckout.cmake) file and include it in the CMake project.
19+
- Use [`file(DOWNLOAD)`](https://cmake.org/cmake/help/latest/command/file.html#download) to automatically download the `GitCheckout.cmake` file.
20+
- Use [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) to add this package to the CMake project.
21+
22+
## Example Usages
23+
24+
This example demonstrates how to clone and check out a Git repository hosted on GitHub:
25+
26+
```cmake
27+
git_checkout("https://github.com/user/project")
28+
```
29+
30+
### Specify Output Directory
31+
32+
Use the `DIRECTORY` option to specify the output directory for cloning the Git repository:
33+
34+
```cmake
35+
git_checkout(
36+
"https://github.com/user/project"
37+
DIRECTORY path/to/output
38+
)
39+
```
40+
41+
### Specify Checkout Reference
42+
43+
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:
44+
45+
```cmake
46+
git_checkout(
47+
"https://github.com/user/project"
48+
REF latest
49+
)
50+
```
51+
52+
### Use Sparse Checkout
53+
54+
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.
55+
To do this, use the `SPARSE_CHECKOUT` option to list patterns of files to be checked out sparsely:
56+
57+
```cmake
58+
git_checkout(
59+
"https://github.com/user/project"
60+
SPARSE_CHECKOUT src test
61+
)
62+
```
63+
1464
## License
1565

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

0 commit comments

Comments
 (0)