A git repository is a central storage location for managing and tracking changes in files and directories. Think of it as a folder with subfolders and files, but with very detailed tracking of all changes made in it.

All the template code, going from account templates, reconciliation texts, shared parts and export files should be stored in a git repository. This means that you can always work on your own copy of code on your own machine, while maintaining a "master" version in GitHub. This means multiple people can work on the same template code at the same time. This, and many more benefits make git the industry standard for version control for all types of code.

On this page you'll walk through the process of setting up a new repository yourself, connecting with an existing repository and the flow we like to use during our development process.

1. Create a new repository locally

1. Open a terminal, you can do this inside VSCode.

2. Navigate to where you want to save your local copy of the templates.

cd ~/Documents

📘

Navigating directories

When running commands in the terminal, it's important you're executing them from within the right directory. This will become very important once you've got multiple repositories on your machine.

Use cdfollowed by path to navigate to it.
Use pwdto find out your current directory.
Use cd ~ to move to your home directory.
Use cd -to move back to the last directory you were in.
Use cd ..to move up one directory. (to the parent directory)
Use .as an abbreviation that represents your current directory.

3. To create an empty Git repository in this location, run:

git init

You'll use this when you want to turn the folders you created locally into a git repository (which tracks all changes compared to the remote repository).

• With the Silverfin CLI you could import the template code from a specific firm to your machine in a specific directory, then turn it into a git repository with this command.

4. Next, create a repository on GitHub.com. It can be empty, but it should have a repository URL that we are going to use in the next step
5. From your terminal, link the local repository to the one in Github:

git remote add origin <repository-url>

To check which remote repository you're connect with, you can always use:

git remote -v

5. At this point, all files within the folder that you have marked as your repository with the git init command earlier, are not present in the remote repository you just created. Therefore the entire content of the local repository needs to be pushed to the remote as a change. To do so, you will need to define the upstream branch. This could be main:

git push -u origin main

2. Set up an existing repository (clone a repository)

In most cases you will just create a local copy of an existing repository, instead of creating a new remote repository.

1. Open a terminal and navigate to where you want to store the local copy of the remote repository.

cd ~/Documents

There are several ways to clone a remote repository to your machine. We recommend either the normal git command with SSH or the GitHub CLI.

You can directly copy-paste the commands you need to clone a specific repository from GitHub. Make sure you've switched to the right tab for this purpose, see the image below (SSH or GitHub CLI)

2. Clone the repository by running this command from the terminal
3. Navigate into the repository

cd silverfin-cli

3. Integrate git in your development process

You have installed git and a repository exists both on GitHub and on your local machine. Now git commands can be used to manage version control of the code in the remote version. Which commands we use exactly, and at which moment, is closely aligned with the development flow for liquid templates.

3.1 Git flow

1. You start a new development task. If there's a system with tickets in place, then this would correlate with moving the ticket to "in progress".
2. You update your local clone of the repository so you always start from the most recent version of the codebase.
   1. You move to the main (or master) branch first if applicable

git checkout main
git pull

📘

Feature branches

When you're working on a big new release that involves updates to several templates, which you want to launch simultaneously, you could use a feature branch.

You will then always start from the latest version of that feature branch instead of main/master, and will merge your own branch with the feature branch. Once the feature is ready to be released, you merge it into main/master.

3. You create a new branch for the assigned task specifically.
   1. In Jira you can set up a connection with Github based on the branch name. You can get the command from your ticket or even through an extension on VSCode. With this command you create a new branch and switch to it in one go.

git checkout -b <branch_name>

You can switch branches with git checkout <branch_name>
You can create a new branch with git branch <branch_name>
You can get an overview of all the branches with git branch

Branching allows multiple people to work on the same template without necessarily interfering with each other.
You write your update on your branch, once you’re done it will be merged with the main branch and your branch can be deleted.

4. You adjust a file. As with any other local copy of a file, you need to save your work. Press CMD S or CTRL S.
5. Once you're happy with the work you've done, maybe you've finished up a specific part of the task that was assigned to you, you bring the saved changes to the so called "staging area".

git add .

This command will stage all the changes you've made so far. If you only want to stage the changes in a specific file, you need to specify every file you want to include.

git add <file>

The changes that you stage will be part of your next commit. Ideally each commit represents a single or at least coherent change to the codebase. For example, if your template exists out of 3 different tables, you could stage your changes once the first table is built and write your first commit. This becomes even more relevant when your change includes multiple files, for example if you also added translations to a part and introduced a new result in another reconciliation text.

6. You can review your staged changes before committing them. (optional)

git status
git status --short
git diff --cached

In VS code, it is possible to click on the staged change in the source control section, to see the differences with the branch origin.

7. You've finished a piece of code and are ready to commit it.

git commit -m "description of the changes"

Commits are crucial as they capture your files at a specific point in time and serve as anchor points in the historical record of your repository. You'll be able to look at the state of the codebase at the time of any specific commit. You can always rollback to a previous commit. If you commit frequently and in meaningful chunks, the commit log becomes a very useful tool for anyone else who looks at the same repository. The changes to the project are easier to read, track, review and debug.

For an overview of your commits, run:

git log
git log --oneline

8. You will repeat steps 4-7 multiple times until the work for this particular task is done.

During development, it is good practice to regularly rebase your code. By rebasing you add commits that have been made to the main branch (or feature branch) chronologically to your local branch. Take the following steps: Switch to main, update main, switch to your local branch, rebase your branch:

git checkout main
git pull
git checkout <branch name>
git rebase main

9. After finishing a number of commits (and rebases), you can send your committed changes to the remote instance of your current working branch (the "upstream" branch):

git push

You don't have to wait until all the work is finished to push to the remote repository. As soon your work is ready on your own branch, you can push your commits to the upstream branch. This could be useful if you want to share a piece of code with another developer that's part of one of your commits, even though you're not ready yet with the task as a whole. Your changes will be gathered in the remote version of your branch, which is the place where they will later be reviewed and merged with main. I.e. pushing to the remote branch does not mean your code is ready for review.

If it's the first time pushing your code from your local branch to the remote repository, you'll get an error from git because the branch does not have an upstream branch yet. But it will also give you the command you need to run to set the upstream. Easy!

git push --set-upstream origin [branch name]

10. After you've pushed your code, you'll receive the suggestion to create a pull request. A pull request is a page on GitHub that all team members can use to approve your upstream working branch to be merged into the main branch. You can visit the link provided in your browser to finalize the PR.

11. You can open Pull Requests either on Github or use the Pull Requests extension in VSCode. With the latter you can checkout the branch of a PR, view the changes, add comments and even start making changes on the current state of these files. This comes in handy when you are the code reviewer of a PR.
    Typically your request will be reviewed by someone else. If you're using a ticket system like Jira, this is the point where you move your ticket to "In Review".
12. Once the PR pull request is approved by the reviewer and all github actions pass, you can merge the pull request on Github and with the extension. You can also merge branches in your local repository though.

git merge <branch name>

Another common approach is to rebase your code. By rebasing you add commits that have been made to the main branch (or feature branch) to your local branch. It's good to rebase regularly if it takes a while for you to finish the task at hand. Take the following steps: Switch to main, update main, switch to your local branch, rebase your branch.

git checkout main
git pull
git checkout <branch name>
git rebase main

11. Once the Pull Requests has been approved and merged into the main branch, you can delete your branch.
    (but make sure you're not in a branch you're about to delete!). If there's no outstanding changes to documentation or tests, you can move your ticket to done.

git checkout main
git branch -d <branch name>

3.2 Git best practices (coming soon)

Atomic commits

Write a lot of commits. Make the commits small. Smaller commits are easier to read for people that don't know the code (yet) but e.g. have to review it.

The commits need to make sense (identifiable and coherent).

Merge vs Rebase

When multiple people are working on the same project, and especially when they are working on the same code (shared parts e.g.), it can be easier to merge your changes into the repository.

In all other cases, you might opt for rebasing. With rebase you insert the commits that have been made to the repository since the creation of your branch into your local codebase. That way you continue working on the most up to date version of the code and reap the benefits of the updates that have been made in the mean time.