Branches

Starting Point

You have the following file that is tracked by git:

% paper.tex
\documentclass{article}

\title{My Paper}
\begin{document}
\maketitle

\section{Introduction}
\section{Numerical results}
\section{Conclusion}

\end{document}

You now want to work on the section about numerical results. You obviously can work on the master branch but here, for educational purpose, you will create a dedicated branch named numerical. Right now, your git working directory must be cleaned, otherwise please do a commit:

❯ git status
On branch master
nothing to commit, working tree clean

Creating a branch

This is simply done by typing

❯ git branch numerical

Existing branches can be shown by typing (the star denotes on which branch we are)

❯ git branch
* master
  numerical

We see that the branch numerical has been created but git is still based on the master branch. To switch to another branch, use git checkout:

❯ git checkout numerical
Switched to branch 'numerical'

The command git checkout can do quite a lot of different actions: remove change in working area, switch branch, … Git v2.23 adds two new commands to clearly separate these actions:

  • git restore <filename> to cancel changes of the file filename in the working area
  • git switch <branch> to switch to the branch

As they are still experimental, we still use checkout in this tutorial but feel free to be modern!

Working on differents branches

Branch numerical

Check that git has switched to branch numerical. Add some random text in the “Numerical Results” section:

% paper.tex
\documentclass{article}

\title{My Paper}
\begin{document}
\maketitle

\section{Introduction}
\section{Numerical results}
Results are very impressive especially for this function:
\[
F(y) = 4y
\]
\section{Conclusion}

\end{document}

Now commit these changes

❯ git commit -m "short intro to numerical result" -a

Switching between branches

You are now totally unhappy with the title of your paper and want to change it. It might be confusing to operate this change in the numerical branches rather than in the master branch. Let switch to the master branch

❯ git checkout master

Your file has come back to the previous version! Now change the title of the paper (\title{...}):

% paper.tex
\documentclass{article}

\title{A very powerful result}
\begin{document}
\maketitle

\section{Introduction}
\section{Numerical results}
\section{Conclusion}

\end{document}

Commit these changes:

❯ git commit -m "Change title" -a

You can switch to the numerical branch if you want and come back to master to see the effect.

Merging a branch into master

We are quite happy with the changes provided in the numerical branch and want these changes to be available in the master branch. In git, we say that the branches will be merged. When merging two branches, git create a new commit which will be the fusion of the two branches. If there are no conflict then everything is automatic, otherwise, the user must manually solve the conflict.

To merge the branch numerical onto master, proceed as follows:

❯ git checkout master
❯ git merge numerical -m "Numerical part"
Auto-merging paper.tex
Merge made by the 'recursive' strategy.
 paper.tex | 4 ++++
 1 file changed, 4 insertions(+)

A new commit has been created which is the fusion of both branches. Your file paper.tex now contains all the changes. Your history look like the following

After merging two branches, both of them still exist. In our case, we should delete the branch numerical:

❯ git branch -D numerical

A simple conflict

We are going to check what to do when conflict happens. To proceed, we create a branch and change the title of the paper in both this new branch and the master one.

  • Create a branch conflict and switch to it
❯ git branch conflict
❯ git checkout conflict
  • Change the title of the paper in \title{Title of Conflict branch}, save and commit.
  • Switch to the master branch, change the title of the paper to another title, say \title{The master Title}. Save and commit.
  • Merge
❯ git checkout master
❯ git merge conflict -m "Testing conflict"
Auto-merging paper.tex
CONFLICT (content): Merge conflict in paper.tex
Automatic merge failed; fix conflicts and then commit the result.

Have a look at paper.tex, you should see some strange lines:

<<<<<<< HEAD
\title{The master Title}
=======
\title{Title of the conflict branch}
>>>>>>> conflict

You can see that there is a conflict on the title part: git does not know what to chose. To solve the conflict, you have to chose between the two (You can also choose to remove everything!). Here we are going to keep the change that have been made in master branch. To do that, remove each line except the one you want to keep:

\title{The master Title}

Now you can continue the merging process, which is, actually, a commit process:

❯ git add paper.tex
❯ git commit -m "conflict solve"
[master f72487c] conflict solve

Solving a conflict using only a text editor without plugin might be unconfortable (actually, it is totally). Modern tools are then very useful! For example, Emacs can be extended with plugins as magit to manage git and VS Code provides git integration natively where, for example, conflict can be solved using graphical interface.

Illustration

More information on VS Code are provided in the dedicated section.

Précédent
Suivant