In this lesson we are going to learn how to create our own starter templates for Git. For our example we’ll change the default branch name from `master` to `main`.
In this lesson we are going to learn how to create our own starter templates for Git. For our example we’ll change the default branch name from master
to main
.
Templates in Git are the starting files and settings for all new Git repositories. Any files not starting with a dot (hidden files) will be copied to the new Git repository upon initialization.
These template files are stored in a global system location and unless you tell Git otherwise it will use this location as the source for all new Git repositories. When we tell Git to use a different location it will use those files isntead. We’ll edit one of those files to change the default branch name.
But first we need to find the templates.
The template files are stored inside of the git-core
directory in your local Git installation. However, where Git is installed and stored will depend on your installation of Git.
You’d think if we run:
which git
That we would get the location. But that’s not true: this is the location of the Git binary that is run, not the supporting files. It took me a little time to find mine but I was able to located them using the find
command.
If you don’t know where the templates directory is located on your own system, you can try to find git-core
(on macOS or Linux):
find / -name git-core
The find
command isn’t fast but it’s pretty thorough. For my installation of macOS Catalina using the default system Git that is installed by the developer Command Line Tools, the Git templates are located here:
/Library/Developer/CommandLineTools/usr/share/git-core/templates
Your location may be different depending on how you have Git installed. The standard installation for Git is /usr/share/git-core/templates
but as you can see mine is slightly different and OS-specific.
We don’t want to alter the system version of these templates but instead make our own copy. To be sure we don’t mess anything up, we’ll copy the entire templates directory to our user directory.
First, we’ll create the destination directory for the user copy of the templates. You can put it anywhere you want, including up the tree further but I like to store it with my user. So, to that end, I’ll create a directory in my user directory called git-templates
.
mkdir ~/git-templates
And then we’re ready to copy the core files into our user directory:
cp -a /Library/Developer/CommandLineTools/usr/share/git-core/templates ~/git-templates
The -a
option is set to preserve structure and attributes of the files and copy recursively. It’s a shorthand option instead of -pPR
.
Next we’re going to create a HEAD
file in our templates directory and populate it with the default name of our branch.
We’ll just echo
a setting into it. Git will create the HEAD
file if it doesn’t exist. When we create a new project it will copy this file along with the rest of the files. In doing this we’re telling Git to create the first branch (a ref) and call it main
.
echo 'ref: refs/heads/main' > ~/git-templates/HEAD
(Use your own path for the location of your templates directory.)
Now that we have the templates code copied over and customized, we need to tell Git to use it when it initializes a new repository. The easiest way to do this is to just set the settings using the git config
command. This sets whatever you tell it to either the project or global config file. The global config file is typically in your user directory, which is what we want to use:
git config --global init.templateDir ~/git-templates
We specify it as a global setting, tell it the setting to set and then the location to write for that setting.
If we take a peek at the config file we should see it in there.
more ~/.git-config
And we should see it at the bottom of the config file:
[init]
templateDir = /Users/ryan/git-templates
Initalizing a new repository that uses the new settings isn’t any different than before. But now, instead of using the default templates location, Git is going to use our custom location in our user directory. Because of that Git will also create the initial branch called main
instead of master
because of what we specified in the HEAD
file.
Let’s try it out.
cd ~/training
git init git-templates-test
This will will initialize a new repository in the git template-test
directory (which it’ll also create for us).
ryan@MPB training $ git init git-templates-test
Reinitialized existing Git repository in /Users/ryan/training/git-templates-test/.git/
Now if we run git status
we should see the branch listed:
ryan@MPB git-templates-test $ git status
On branch main
No commits yet
nothing to commit (create/copy files and use "git add" to track)
Let’s add and commit a file:
touch README.md
git add README.md
git commit -m "adding readme"
[main (root-commit) 0e4e519] adding readme
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 README.md
Now if we run git status
we will see the clean branch again. And, if we run git branch
we’ll see our main branch listed:
ryan@MPB git-templates-test (main)$ git branch
* main
And, there we have it. We’ve now changed the default branch name of our Git repository from master
to main
.