Using Custom Templates in Git (to change the default branch name)

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 les­son we are going to learn how to cre­ate our own starter tem­plates for Git. For our exam­ple we’ll change the default branch name from master to main.

What Are Git Tem­plates in Git?

Tem­plates in Git are the start­ing files and set­tings for all new Git repos­i­to­ries. Any files not start­ing with a dot (hid­den files) will be copied to the new Git repos­i­to­ry upon initialization. 

These tem­plate files are stored in a glob­al sys­tem loca­tion and unless you tell Git oth­er­wise it will use this loca­tion as the source for all new Git repos­i­to­ries. When we tell Git to use a dif­fer­ent loca­tion 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.

Find­ing the Templates

The tem­plate files are stored inside of the git-core direc­to­ry in your local Git instal­la­tion. How­ev­er, where Git is installed and stored will depend on your instal­la­tion of Git. 

You’d think if we run:

which git

That we would get the loca­tion. But that’s not true: this is the loca­tion of the Git bina­ry that is run, not the sup­port­ing files. It took me a lit­tle time to find mine but I was able to locat­ed them using the find command.

If you don’t know where the tem­plates direc­to­ry is locat­ed on your own sys­tem, you can try to find git-core (on macOS or Linux):

find / -name git-core

The find com­mand isn’t fast but it’s pret­ty thor­ough. For my instal­la­tion of macOS Catali­na using the default sys­tem Git that is installed by the devel­op­er Com­mand Line Tools, the Git tem­plates are locat­ed here:


Your loca­tion may be dif­fer­ent depend­ing on how you have Git installed. The stan­dard instal­la­tion for Git is /usr/share/git-core/templates but as you can see mine is slight­ly dif­fer­ent and OS-specific.

Copy­ing the Core Templates

We don’t want to alter the sys­tem ver­sion of these tem­plates but instead make our own copy. To be sure we don’t mess any­thing up, we’ll copy the entire tem­plates direc­to­ry to our user directory.

First, we’ll cre­ate the des­ti­na­tion direc­to­ry for the user copy of the tem­plates. You can put it any­where you want, includ­ing up the tree fur­ther but I like to store it with my user. So, to that end, I’ll cre­ate a direc­to­ry in my user direc­to­ry 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 pre­serve struc­ture and attrib­ut­es of the files and copy recur­sive­ly. It’s a short­hand option instead of -pPR.

Set­ting the Default Branch Name

Next we’re going to cre­ate a HEAD file in our tem­plates direc­to­ry and pop­u­late it with the default name of our branch. 

We’ll just echo a set­ting into it. Git will cre­ate the HEAD file if it doesn’t exist. When we cre­ate a new project it will copy this file along with the rest of the files. In doing this we’re telling Git to cre­ate the first branch (a ref) and call it main.

echo 'ref: refs/heads/main' > ~/git-templates/HEAD

(Use your own path for the loca­tion of your tem­plates directory.)

Set­ting the Git Con­fig to Use Cus­tom Templates

Now that we have the tem­plates code copied over and cus­tomized, we need to tell Git to use it when it ini­tial­izes a new repos­i­to­ry. The eas­i­est way to do this is to just set the set­tings using the git config com­mand. This sets what­ev­er you tell it to either the project or glob­al con­fig file. The glob­al con­fig file is typ­i­cal­ly in your user direc­to­ry, which is what we want to use: 

git config --global init.templateDir ~/git-templates

We spec­i­fy it as a glob­al set­ting, tell it the set­ting to set and then the loca­tion to write for that setting.

If we take a peek at the con­fig file we should see it in there.

more ~/.git-config

And we should see it at the bot­tom of the con­fig file:

        templateDir = /Users/ryan/git-templates

Ini­tial­iz­ing a Repos­i­to­ry with Cus­tom Templates

Ini­tal­iz­ing a new repos­i­to­ry that uses the new set­tings isn’t any dif­fer­ent than before. But now, instead of using the default tem­plates loca­tion, Git is going to use our cus­tom loca­tion in our user direc­to­ry. Because of that Git will also cre­ate the ini­tial branch called main instead of master because of what we spec­i­fied in the HEAD file.

Let’s try it out.

cd ~/training
git init git-templates-test

This will will ini­tial­ize a new repos­i­to­ry in the git template-test direc­to­ry (which it’ll also cre­ate 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 com­mit a file:

git add
git commit -m "adding readme"

[main (root-commit) 0e4e519] adding readme
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644

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 repos­i­to­ry from master to main.