How to use Git to downstream changes from a template

Jason Long — http://git-scm.com/downloads/logos

Last week I had to update the version of Gradle Enterprise in a template and downstream the changes to all its implemented projects. I was fascinated how useful this is, especially if you have many projects that build on the same base. I only had to update the template and downstream the changes but in this article I will also describe how to create one of these templates and how to use it in a project.

Why to use a Template

A template has the purpose of sharing boilerplate code across the whole codebase, which reduces the time needed to start a new project and gives you more time to focus on the important stuff. More information here.

Creating the Template

First of all, we need to create a new git repository on our favourite platform like GitHub, Bitbucket or GitLab. We can now clone the empty repository to our local machine and add the files we want in our template.

$ git clone <link to the repo>

Then we just push the changes to the remote again.

$ git add .
$ git commit -m "Initial Commit"
$ git push

Congratulations, you just created your first template

Setting up the Project

After creating the template, we can create a new repo for our project. After this is done, clone the template repo but with a different name than the standard repo name.

$ git clone <link to the template> <name of the project>

Git will still create the remote origin configurations with the up- and downstream URLs pointing to the template.

$ git remote -v
origin <link to the template> (fetch)
origin <link to the template> (push)

Since we want to push to our own project instead of the template itself, we need to rename the origin.

$ git remote rename origin upstream

This way, the default location to push and fetch changes from is the project repository. At the moment, we would be able to still push changes to the template with:

$ git push upstream

Which should not be possible… To change that, we can change the URL of the push upstream to no_push .

git remote set-url --push upstream no_push

If we now use the git remote -v command, we will see something like this:

$ git remote -v
origin <link to the template> (fetch)
origin <link to the template> (push)
upstream <link to the template> (fetch)
upstream no_push (push)

If we now try to push something to the upstream, we get an exception that tells us that this repository does not exist.

$ git push upstream
fatal: 'no_push' does not appear to be a git repository
fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.

Downstream from the template

First of all, we have to fetch the newest changes of the remote with:

$ git fetch 

Next, we can merge the changes, resolve conflicts if there are some and push to the project.

$ git merge upstream/master
$ git add .
$ git commit -m "Downstreamed changes from template"
$ git push 

Now you have successfully downstreamed the changes of the template to your own project. Congratulations 👍 😸

Reflection

What went good

Since this was a pretty easy and well known task, I had no problem to find good resources on this topic.

What needs improvement

This has not directly todo with the downstreaming itself but in the future I would research a little more about the dependencies to versions of other projects. The project I was upgrading had some dependencies to a specific version of another project. I didn’t know that and was wondering about the errors the whole time until I asked someone of my team for help.