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

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:

/Library/Developer/CommandLineTools/usr/share/git-core/templates

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:

[init]
        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:

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