Git branches¶

Questions

How to not ruin working code when adding new features?
How to work on parallel tracks (many developers, versions)?
How to fix mistakes?

Learning objectives of 'Branches'

learners can
- explain and evaluate the usefulness of branches
- create, switch and delete a git branch locally

Instructor notes

Prerequisites are:

git basics

Lesson Plan:

Total 50 min
Theory 20
Exercise 20
Discussions 10 min

References

The main git book
'git best practices'
- Tsitoara, Mariot, and Mariot Tsitoara. "Git best practices." Beginning Git and GitHub: A Comprehensive Guide to Version Control, Project Management, and Teamwork for the New Developer (2020): 79-86.
- Tepavac, Igor, et al. "Version Control Systems, Tools and Best Practices: Case Git." CASE 27-Razvoj poslovnih i informatičkih sustava. 2015.

Branching and merging¶

Software development is often not linear:

We typically need at least one version of the code to "work" (to compile, to give expected results, ...).
At the same time we work on new features, often several features concurrently. Often they are unfinished.
We need to be able to separate different lines of work really well.

Isolated tracks of work.

The strength of version control is that it permits the researcher to isolate different tracks of work, which can later be merged to create a composite version that contains all changes.

We see branching points and merging points.
Main line development is often called master or main.
Other than this convention there is nothing special about master or main, it is just a branch.
A group of commits that create a single narrative are called a branch.
There are different branching strategies, but it is useful to think that a branch tells the story of a feature, e.g. "fast sequence extraction" or "Python interface" or "fixing bug in matrix inversion algorithm".

Three ways to name a branch

Issues
Features
Personal

Typical workflows¶

One typical workflow:

git branch new-feature  # create branch, switch to it
git add/commit                   # work, work, work, ..., and test
git switch master          # once feature is ready, switch back to master
git branch                   # make clear which branch you are in
git merge new-feature        # merge work to present branch
git branch -d new-feature    # remove branch

Test¶

- What is a branch?
- What is the problem that branches alleviate?
- What is the name/names of the most important branch?
- What is our git branching setup?
- What is the goal of that setup?
- Why do we use that setup instead of a different one?
- What is the purpose of each of those branches?
- Does creating a branch create a new version? Why?
- Does changing a branch change the content of your local computer? Why?
- Does deleting a branch create a new version? Why?

git push doesn't work with new branch

you always have to pull before a push:

git pull #

You may need to be more detailed:

git push --set-upstream origin new-branch

Exercises¶

Exercise 1: create, switch and delete a `git` branch¶

Learning objectives

Create, switch and delete a git branch
Build up experience using git without troubleshooting

gitGraph
    commit id: "Before start"
    commit id: "Branching version"
    branch sven
    checkout sven
    commit id: "Modify my file"
    commit id: "Delete branch" type: HIGHLIGHT
    checkout main
    commit id: "Another commit"

For our shared GitHub repository, create a branch with your first name that is unique, e.g. sven, sven_svensson or sven_svensson_314. You may branch of from main or develop (if it exists). You may use the web interface (easiest!) or use the command line
On your local computer:
- update the repository
- switch to the new branch
- change the content of the repository, for example, by creating a file in learners/[your_name]/[your_name]_is_on_[your_branch_name]
- push your changes online.
On GitHub, verify that your changes on your branch can be found online
On your local computer, switch to the main branch, as we'll delete the branch you are on now
Delete your branch (i.e. the one with the unique name). You may use the web interface (easiest!) or use the command line
On your local computer, update your code

Answers

For our shared GitHub repository, create a branch with your first name that is unique, e.g. sven, sven_svensson or sven_svensson_314. You may branch of from main or develop (if it exists). You may use the web interface (easiest!) or use the command line

github_create_branch_annotated

Click on 1, type your branch name at 2 (in this case, richel), then click 3. Done!

On your local computer:

update the repository

On your local computer, navigate to the folder of the shared project and update:

git pull

On your local computer:

switch to the new branch

Switch to the new branch, for example, richel, by doing:

git switch richel

On your local computer:

change the content of the repository, for example, by creating a file in learners/[your_name]/[your_name]_is_on_[your_branch_name]

This can be any change you'd like. To create a file under Linux (and maybe this works on other operating systems too), one can do:

touch learners/richel/richel_is_on_richel.txt

After the change, commit these:

git add .
git commit -m "Richel is on richel"

On your local computer:

push your changes online.

Do:

git push

And your code may end up online.

If that does not work, do:

git pull

and try pushing again, maybe multiple times, as many people are pushing to the shared repo.

On GitHub, verify that your changes on your branch can be found online

github_pushed_to_branch

Make sure you look at the correct branch, as displayed at 1. Then your commit message shows up at 2.

On your local computer, switch to the main branch, as we'll delete the branch you are on now

Switch to the main branch, for example, main, by doing:

git switch main

Delete your branch (i.e. the one with the unique name). You may use the web interface (easiest!) or use the command line

github_view_branches_annotated

Click on 'Branches', as shown in the image above.

github_view_all_branches_annotated

Click on garbage bin, as shown in the image above.

github_view_all_branches_just_deleted_annotated

The branch will now be deleted, as shown in the image above.

On your local computer, update your code

Do:

git pull

Need a video?

See a video here

Summary¶

Now we know how to save snapshots:

git add <file(s)>
git commit

And that is what we do as we program.
Other very useful commands are these:

git init    # initialize new repository
git add     # add files or stage file(s)
git commit  # commit staged file(s)
git status  # see what is going on
git log     # see history
git diff    # show unstaged/uncommitted modifications
git show    # show the change for a specific commit
git switch -b wild-idea    # create branch, switch to it, work, work, work ...
git switch main          # realize it was a bad idea, back to main/master
git branch -D wild-idea      # it is gone, off to a new idea
git merge

Overview workflow

git branches

Parts to be covered!

☑ Source/version control
- Git
- We have a starting point!
- GitHub as remote backup
- branches
☑ Planning
- ☑ Analysis
- ☑Design
☑ Testing
- Different levels
☐ Collaboration
- GitHub
- pull requests
☐ Sharing
- ☑ open science
- ☐ citation
- ☑ licensing
☐ Documentation
- ☑ in-code documentation

Keypoints

Initializing a Git repository is simple: git init.
Commits should be used to tell a story.
Git uses the .git folder to store the snapshots.
Don’t be afraid to stage and commit often. Better too o
A branch is a division unit of work, to be merged with
A tag is a pointer to a moment in the history of a proj
A repository can have one or multiple remotes (we will
Local branches often track remote branches.
A remote serves as a full backup of your work.