Quick recap on Git Basics: Commits and Branches
The first and most basic task to do in Git is record changes using
commits.
We will record changes in two ways:
on a new branch (which supports multiple lines of work at once)
directly on the “main” branch (which happens to be the default branch here).
Objectives
Record new changes to our own copy of the project.
Understand adding changes in two separate branches.
See how to compare different versions.
Glossary
commit: Snapshot of the project at a certain point in time, gets a unique identifier (called a hash, e.g.
c7f0e8bfc718be04525847fc7ac237f470add76e). Usually you can be lazy and use only the first 4 characters wherever a commit hash is needed.branch: Independent development line. The main development line is often called
main.tag: A pointer to one commit, to be able to refer to it later. Like a “commemorative plaque” that you attach to a particular commit (e.g.
phd-printedorpaper-submitted).repository: A copy of the project, contains all data and history (commits, branches, tags).
forge: a web-based collaborative software platform for both developing and sharing code (from wikipedia), e.g. GitHub or GitLab
cloning: Copying the whole repository - the first time, e.g. downloading it on your computer. It is not necessary to download each file one by one.
forking: Cloning a repository (which is typically not yours) on a forge - your copy (fork) stays on the forge and you can make changes to your copy.
Merging
What if two people, at the same time, make two different changes? Git can merge them together easily. Image created using https://gopherize.me/ (inspiration).
Exercise: Practice creating commits and branches
How to prepare the repository
Go to the repository view on GitHub https://github.com/coderefinery/recipe-book
First, on GitHub, click the button that says “Fork”. It is towards the top-right of the screen:
You should shortly be redirected to your copy of the repository YOUR_USER_NAME/recipe-book.
At all times you should be aware of if you looking at your repository or the CodeRefinery upstream repository.
Your repository: https://github.com/USERNAME/recipe-book
CodeRefinery upstream repository: https://github.com/coderefinery/recipe-book
This is necessary if you plan to use another forge than github.com. It can also be a useful exercise.
Exercise
In order to achieve an equivalent result, you need to
clone the repository https://github.com/coderefinery/recipe-book locally on your computer
create a properly named repository on the forge of your choice
push the newly created repository there.
Detailed steps
Please follow these steps. The Bash command needed for each step are shown along.
create a directory called
centralized-workflow-exerciseon your computer.mkdir centralized-workflow-exerciseclone the repository https://github.com/coderefinery/recipe-book on your computer in the directory you just created:
git clone https://github.com/coderefinery/recipe-bookLog into your preferred forge and create an empty and public repository called
recipe-book.On GitLab, click the blue “New Project” button on the top right part of the page. Among other things, remember to:
Choose “Blank Project”,
Set the Visibility Level to be Public (this can be changed later)
untick the box close to “Initialize repository with a README”
On codeberg.org, click the
+symbol on the top right corner of the page, and Choose the “New Repository” option.
Add the remote to your local repository. In this case, we will use the name of the forge as the name of the remote. If you configured ssh access:
git remote add <forge-name> git@<forge-name>:<username>/recipe-bookIf not, you can try https instead:
git remote add <forge-name> https://<forge-name>/<username>/recipe-bookPush the main branch there:
git push <forge-name> main
Have a look at the Authentication: connecting to the repository from your computer section if you have troubles problems during the push.
We offer three different paths of how to do this exercise:
on GitHub
using VSCode
using the command line
Exercise: Practice creating commits and branches (20 min)
Make sure that you now work on your fork of the recipe-book repository (
USER/recipe-book, notcoderefinery/recipe-book)First create a new branch and then add a recipe to the branch and commit the change.
In a new commit, modify the recipe you just added.
Switch to the
mainbranch and modify a recipe there.Browse the network and locate the commits that you just created (“Insights” -> “Network”).
Compare the branch that you created with the
mainbranch. Can you find an easy way to see the differences?Can you find a way to compare versions between two arbitrary commits in the repository?
Try to rename the branch that you created and then browse the network again.
Try to create a tag for one of the commits that you created (on GitHub, create a “release”).
The solution below goes over most of the answers, and you are encouraged to use it when the hints aren’t enough - this is by design.
Solution and walk-through
(1) Make sure you are on your fork
You want to see your username in the URL and you want to see the “forked from …” part.
(2) Create a branch and add a recipe to the branch
A recipe template is below. This format is called “Markdown”, but it doesn’t matter right now. You don’t have to use this particular template.
# Recipe name
## Ingredients
- Ingredient 1
- Ingredient 2
## Instructions
- Step 1
- Step 2
There is a main branch that is default. We want to create a
different branch for our new commit, because we will merge it later.
Commit is the verb to describe recording more changes, and also the
name of the thing you make. A commit is identified by something such as
554c187.
Where it says “main” at the top left, click, enter a new branch name
new-recipe, click on the offer to create the new branch (“Create branch new-recipe from main”).
Change to some sub-directory, for example
sidesMake sure you are still on the
new-recipebranch (it should say it at the top), and click “Add file” → “Create new file” from the upper right.Enter a filename where it says “Name your file…”, with a
.mdat the end. Example:mixed-nuts.md.Enter the recipe. You can use the template above.
Click “Commit changes”
Enter a commit message. Then click “Commit changes”.
You should appear back at the file browser view, and see your new recipe there.
Make sure that you are on the main branch.
Version control button on left sidebar → Three dots in upper right of source control → Branch → Create branch.
VS Code automatically switches to the new branch.
Creating a new branch in VS Code.
Create a new file, for example
sides/mixed-nuts.md.In the version control sidebar, click the
+sign to add the file for the next commit.Enter a brief message and click “Commit”.
Committing a new file in VS Code.
Create a new branch called new-recipe from main and switch to it:
$ git switch --create new-recipe main
Then create the new file. Finally add and commit the file:
$ git add sides/mixed-nuts.md
$ git commit -m "Add mixed nuts recipe"
(3) Modify the recipe with a new commit
This is similar to before, but we click on the existing file to modify.
Click on your new recipe, for example
mixed-nuts.md.Click the edit button, the pencil icon at top-right.
Follow the “Commit changes” instructions as in the previous step.
Repeat as in the previous step.
Modify the file. Then commit the new change:
$ git add sides/mixed-nuts.md
$ git commit -m "Short summary of the change"
Make sure to replace “Short summary of the change” with a meaningful commit message.
(4) Switch to the main branch and modify a recipe there
Go back to the main repository page (your user’s page).
In the branch switch view (top left above the file view), switch to
main.Modify another recipe that already exists, following the pattern from above. Don’t modify the one you just created (but it shouldn’t even be visible on the
mainbranch).
Use the branch selector at the bottom to switch back to the main branch. Repeat the same steps as above.
Switching branch via selector at bottom.
First switch to the main branch:
$ git switch main
Then modify a file. Finally git add and then commit the change:
$ git commit -m "Short summary of the change"
(5) Browse the commits you just made
Let’s look at what we did. Now, the main and new-recipe branches
have diverged: both have some modifications. Try to find the commits
you created.
Insights tab → Network view (just like we have done before).
This requires an extension. Opening the VS Code terminal lets you use the command line method.
View → Terminal will open a terminal at bottom. This is a normal command line interface and very useful for work. (Note the git-aware prompt that shows the current branch. This requires other setup.)
$ git log --graph --oneline --decorate --all
In my case I got:
* b4de93b (HEAD -> main) add spring onion to poke
| * dc5d6f0 (origin/new-recipe, new-recipe) adding chocolate to the mixed nuts recipe
| * b4035e3 add mixed nuts recipe
|/
* 554c187 (origin/main, origin/HEAD) Merge branch 'alex/fruit-salad'
|\
| * 89d5ef9 fruit salad: instructions
| * 3bd2468 fruit salad: ingredients
* | 8bcb766 a todo note to not forget the instructions
|/
* b950c5c just fixing capitalization
* d18035e fix formatting
* 7051cca add some cilantro
* ae19e81 add categories for easier browsing
* a6fe629 we also need salad
* 30b89c4 document what this is about
* fd12dc1 Merge branch 'radovan/lasagna'
|\
| * 7753d43 vegetarian lasagna: instructions
| * aa0473e vegetarian lasagna: ingredients
* | 1e5a24a Merge branch 'radovan/poke'
|\ \
| * | 5aa6687 oh no! forgot onion - adding
| * | cc84e4f working on a poke recipe
| |/
* | 9500901 a classic pumpkin pie recipe - yum!
* | 34ce939 drafting a recipe for a pasta, so far only ingredients
* | 28e5f26 recipe for a mushroom soup
|/
* a550963 reduce amount of salt
* f2d6d58 don't forget to enjoy
* 1fde064 add half an onion
* 4c1873e drafting a guacamole recipe
* 2992443 this will be licensed under CC0
* 084a1ea starting with an almost empty readme
(6) Compare the branches
Comparing changes is an important thing we need to do. When using the GitHub view only, this may not be so common, but we’ll show it so that it makes sense later on.
Next to the branch name switcher, click on “Branches” to get an overview.
Another way to compare branches or commits on GitHub is to adjust the following URL:
https://github.com/USER/recipe-book/compare/VERSION1..VERSION2
Replace USER with your username and VERSION1 and VERSION2 with a commit hash or branch name.
Please try it out.
This seems to require an extension. We recommend you use the command line method.
$ git diff main new-recipe
Try also the other way around:
$ git diff new-recipe main
Try also this if you only want to see the file names that are different:
$ git diff --name-only main new-recipe
(7) Compare two arbitrary commits
This is similar to above, but not only between branches.
Like above, one can compare commits on GitHub by adjusting the following URL:
https://github.com/USER/recipe-book/compare/VERSION1..VERSION2
Replace USER with your username and VERSION1 and VERSION2 with a commit hash or branch name.
Please try it out.
Again, we recommend using the Command Line method.
First try this to get a short overview of the commits:
$ git log --oneline
Then try to compare any two commit identifiers with git diff.
(8) Renaming a branch
Branch button → View all branches → three dots at right side → Rename branch.
Version control sidebar → Three dots (same as in step 2) → Branch → Rename branch. Make sure you are on the right branch before you start.
Renaming the current branch:
$ git branch -m better-recipe
Renaming a different branch:
$ git branch -m new-recipe better-recipe
(9) Creating a tag
Tags are a way to mark a specific commit as important, for example a release version. They are also like a sticky note, but they don’t move when new commits are added.
Click on the branch switcher, and then on “Tags”, then on “View all tags”, then “Create a new release”:
What GitHub calls releases are actually tags in Git with additional metadata. For the purpose of this exercise we can use them interchangeably.
Version control sidebar → Three dots (same as in step 2) → Tags → Creat tag. Make sure you are on the expected commit before you do this.
Creating a tag:
$ git tag -a v1.0 -m "New manuscript version of my recipe for the pre-print"
If this repository has a remote called origin,
you can publish the tag there:
$ git push origin v1.0
Discussion
In this part, we saw how we can make changes to our files. With branches, we can track several lines of work at once, and can compare their differences.
You could commit directly to
mainif there is only one single line of work and it’s only you.You could commit to branches if there are multiple lines of work at once, and you don’t want them to interfere with each other.
Tags are useful to mark a specific commit as important, for example a release version.