Starting any project on a clean page can be daunting, whether it is writing prose, or writing code. This can be especially frustrating if the setup process for projects should be the same each time – or if you are just starting out with coding and are not sure of what would be useful to have in the project. In 2019 Github addressed this problem by introducing template repositories, enabling you to skip the blank page, and get straight to the core of your project.
Using a template differs from simply forking a repository – a link to the original repository is not kept, and the commit history is cleared. This means your new repository has all the code, but none of the history – it will be easier to keep track of your edits, and your project won't be linked to all other projects forked from the repository. This could be useful for setting up students with a well organised template for their work, encouraging good practice, or for providing yourself with a set of commonly used libraries for your work.
To turn a github repository into a template, follow these actions on the main page of the repository:
- Click the “settings” radio button
- Select the “Template repository” tickbox (under the repository name box)
Using a template repository is simple, you can either:
- Click the “use this template” button on the main page of the repository
- Add /generate to the end of the template repository URL (useful for including in tutorial material)
These both take your user to a “create a new repository” webpage – on which they can chose their account for the new repository, set the repository name, and decide if they want to pull just the master branch, or pull all branches.
Limitations:
- Links to submodules (see previous top tip) get broken – this is on github’s list of features to add in the future.
- Customisation of the new repository isn’t possible during the generation process. An example of how to get around this with placeholder syntax and gomplate, tree and bash is given in the links below.
Further Reading: