When working on large scale software projects, there is often a need to create multiple small projects often following a very similar project template, in may respects often all the way down to the same git repository structure etc. Which may require webhook integrations with with CI/CD servers, permissions, Pull Request templates etc.
When working the dotnet core, you may originally tackle with by creating a project template which can be great solution, however it does come with some limitations and you may find yourself still having to do a lot of the grunt work of configuring your CI/CD project settings etc.
If you're anything like me, you'll find this type task completely boring and mind numbing and I have found these types of tasks are also often the cause of bugs and the source of outdated documentation. Primarily because somebody may forget to update the Wiki page that explains the process to other developers.
These jobs are often what I call pointless process jobs (PPJ), which are basically jobs that still have a human element when in fact they should be completely automated and require no other human interaction other than executing a terminal command.
Git directory template
When using Git on your local machine you can create template directory that you can use to create a typical Git and project structure that you can use when using the git init command.
You can configure your template to configure commong Git hooks, Exclude file patterns and even have a commong directory and project you'll use for your projects. This enables you to create a number of different templates that you can use when starting a new project.
The command-line option to git clone and git init, or as the $GIT_TEMPLATE_DIR environment variable, or as the configuration option init.templatedir. It defaults to /usr/share/git-core/templates.
The template option works by copying files in the template directory to the .git ($GIT_DIR) folder after it has been created. The default directory contains sample hooks and some suggested exclude patterns.
I won't go into to much detail in using Git directory templates here but the Pro Git book provides a good discussion on the subject and the Git Version Control Cookbook
What are Github template repositories
A Template repository enables developers to mark a repository as a template, which they can use later for creating new repositories containing all of the template repository's files and folders and configuration .ie Webhooks etc..
I've previously discussed how to create a Github Repository using the terminal and in this post I'll expand on this and explain how you can create an project, repository and wire up your CI/CD pipeline all by just using Github template repositories
A template repository is a convenient tool start developing new projects with pre-configured starting template with all dependencies, structure and customised automation processes predefined and ready for coding.
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.
Github template repository, in a way, extend and enhance functionality that is provided by a git template directory.
How to create a Github template repository
The GitHub documentation offers a very good example on how to go about creating a repository from a template.
The process is really simple and you can create a new template repository or mark any existing repository as a template with admin permissions. Just navigate to the Settings page and then click on the Template repository checkbox.
Once the template repository is created anyone who has access to it will be able to generate a new repository with same directory structure and files via Use this template button.
If like me you prefer to have the Github CLI installed and prefer to use it to interact with GitHub then you can use the simple CLI command to create your new project and repository
gh repo create threenine/new-repo -p threenine/repotemplate
Checkout the gh repo create for a broader understanding of the command. However the -p switch is for template repository which creates a new repository based on a template repository.
Advantages of using a template repository
- Spend less time on repetitive tasks
- Focus on building new things
- Less manual configuration
- Sharing boilerplate code across the code base
In the sample repository template I created I added all the typical files you may find in a typical C# Microservice project. For instance
- Cake Build Script
- Docker Compose file
- Unit tests
- Custom Project Template
- Custom Directory structure
- Custom Github Pull request template
The idea behind this is just to provide you with an example of how you can include almost any file in your Template Repository.
Why use Github Template repository over a project template
This may be a question many developers will ask and it is a fair question. The answer is quite simply that template repositories enable you to achieve so much more, and and encompasses a whole lot more than just simply a code project template.
A template repository enables your organisation to:
- Copy entire repository Directory structure and files to a brand new repository
- Share repository template throughout your organisation or other GitHub users
- What is this Directory.Packages.props file all about? - January 25, 2024
- How to add Tailwind CSS to Blazor website - November 20, 2023
- How to deploy a Blazor site to Netlify - November 17, 2023