A Git workflow with the terminal
In this guide, we will create a small cook book project using Git. We will add recipes and commit the our repository and then publish the project on GitHub to collaborate with others on it.
Prerequisites
To follow this workflow you need:
- Git installed (see course preparations)
- A GitHub or Gitlab account
- An SSH key to authenticate to GitHub/Gitlab (see here)
All commands that are used in the following, have to be typed in the terminal. If you are on Windows, I recommend to use the Git Bash terminal that comes with the Git installation. On MacOS/Linux, you can just use the standard terminal.
To check if you are ready to go, open the terminal and run
git --versionIf everything is set up correctly it will show you the current installation of Git.
Configure Git
Git needs to know who you are in order to sign your commits correctly. If you already set up GitHub Desktop, you might already have the minimal Git configuration ready.
The Git configuration can be set locally (just for the current repo) or globally (default for all repos without local configuration). Here, we just set a global configuration for all repositories.
To check if you already have a configuration run
git config --global -lIf you don’t yet see a user.name or user.email field or get a message, that the .gitconfig file does not exist, run the following to configure:
git config --global user.name "<your_user_name>"
git config --global user.email "<your_user_email>"Use the user name and email that you also use in your Gitlab/GitHub here.
A Git workflow in the terminal
Step 1: Initialize a new repository
A new Git project can be started in an empty folder or in a folder that already contains files. For this example, we can create an new folder cookBook at a desired location.
When the folder is created, open the terminal and navigate into this folder.
You can use cd /path/to/navigate/to/cookBook to navigate to a specific path. If you want to go back one level, use cd ...
On Windows, you can also right click on the folder that contains your project and then click on Git Bash Here. If you are on Windows 11, you might first have to click on Show more options before this option appears.
To see if you are in the correct directory, have a look at the path that is written on top or your terminal. It should show the directory for the cookbook that you just created. Something like this:
To initialize a Git repo in your cook book project, just run
git initIn the terminal, you can now see the branch that you are currently on. In my case the name of the default branch is main which is now written in blue behind the folder path:
Step 2: Add a recipe
Open your cook book project in the file explorer.
Add a new text file for your favorite recipe. I will add pie.txt. Add the recipe text to the file, e.g.:
Ingredients:
150 g butter
200 g sugar
3 eggs
350 g flour
1 pkg. baking powder
juice from one lemon
Mix everything together and put in the oven
for 45 mins at 200 °C.Save and close the file.
After you added a recipe, switch back to the terminal.
Check the status of your repository with git status
Check the current status of your Git repository by running
git statusThis will show you that pie.txt is a new and untracked file:
Step 3: Stage the new file
With the git add command, you can stage the newly created pie.txt. This means that it is marked to be in the next commit.
git add pie.txtNow you can check the repository status with git status again:
Git tells you, that pie.txt is now ready to be committed.
If you have multiple files, you want to stage, you can do this in one step with
git add *Step 4: Make a commit
To commit the file run
git commitWait for your default text editor to open, and add a commit message and an optional description after a new line:
Add pie recipe
This is my favourite pie in the world.
The recipe comes from my grandfather and
he learned it from his neighbor.Close the text editor and the commit is done.
Look how the status of your repository has changed again with
git statusNo you don’t have any more changes in your project:
Please note that there are guidelines on how to write good commit messages. This becomes especially important when collaborating. Have a look here for some guidelines.
Look at the history
To see how the commit that you just did looks like, run
git logIf you want a shorter summary, you can also use
git log --onelineStep 5: Create a remote repository
Now, we connect our local repository with a remote repository on GitHub.
In the terminal, this is slightly more complicated than with GitHub Desktop.
Go to the GitHub website, log in and click on the green New button on the left of the start page:
Enter a repository name (e.g. cookBook), select if it should be private or public and add a description if you like. Set the check mark for adding a README.md file. This way, the remote already has some content that we can integrate into the local repository:
GitHub will now bring you to the newly created repository.
Add the repository on GitHub as a remote to your local repository
We now want to connect the local cook book project with the remote cookBook on GitHub.
First, copy the remote’s address.
You can find and copy the address by clicking on the green Code button on the right. Choose the SSH address in the middle.
Now switch back to your terminal and add this address as a remote with the name origin. (Replace the address below with the address of your personal repository)
git remote add origin git@github.com:selinaZitrone/cookBook-Selina.gitStep 6: Push new changes to GitHub
You can now push your changes to the remote by running
git push --set-upstream origin mainNow you will get an error message and a warning, that the remote contains commits that you don’t have locally:
This makes sense, because you added a README file when creating the remote repository on GitHub. In these situation, Git prevents you from pushing and you first need to pull all changes from the remote.
Just run
git pullNow you should be able to run
git push --set-upstream origin mainYou only have to do git push --set-upstream origin main when you push a branch for the first time. Afterwards you can just use git push
Collaboration using branching
Git and GitHub are perfect for collaboration. Let’s assume our friend also has a cook-book project on GitHub and we want to work together with them on the book.
If you want to try the workflow by collaborating with yourself, you can just skip step 1 and do the other steps with your own instead of your friend’s cook book.
Add collaborators on GitHub repository
To collaborate, your friend needs to add you to their GitHub project. On the GitHub webpage, they can go to Settings -> Collaborators -> Add people:
Your friend can then add your GitHub user name and you will get an invitation email for the repository. Accept this invitation and you are now a collaborator on your friend’s project.
Step 1: Clone a remote repository
First, we need to clone our friend’s repository. This means we pull an entire copy of the repository onto our machine. To clone a repository, you need to know the repositories address. You can find the SSH address by clicking on the green code button on GitHub:
Open the terminal, navigate to a location where you want to clone the project and run:
git clone git@github.com:selinaZitrone/cookBook-Selina.git(Of course replace the address with the repository you actually want to clone).
Here, I clone my own cookBook-Selina project into the documents folder. Then I use cd to navigate into the newly cloned project. You can see in the last line that I am in a Git repository, because the branch name is indicated in blue:
Step 2: Create a new branch
To use the collaboration workflow discussed in the lecture, you need to create a new branch when you want to do some work. Let’s say, I want to add some vegan pie recipe.
You can create a new branch with the name “add_vegan_pie” just run
git branch add_vegan_pieAfter the branch is created, you need to switch to it with
git checkout add_vegan_pieYou can see that I now switched branches (just look at the blue text):
Now you can start working on your branch and do commits there like you learned earlier.
Step 3: Publish and push your branch to remote
To make your branch with the vegan pie recipe available for you friend, you need to push the branch to the remote repository on GitHub. This works just like with the main branch using git push.
But again, the first time you push a new branch, you need to specify the upstream by running:
git push --set-upstream origin add_vegan_pieNow your branch should be pushed to GitHub and you can do a pull request.
Step 4: Create a pull request
See here for a guide on pull requests.
Other things to try in the terminal
Add a gitignore file
Put a pdf file in your repo
Look at
git status: It should now show that you can commit the pdf file. But for this example, we want to ignore it.Add a gitignore file to your project
.gitignore file on Windows
On Windows, you cannot create a file without a file name. So the Windows explorer will complain if you try to create a file with only the file ending .gitignore. One way around this is to use the terminal. In Git bash, just run
touch .gitignoreto create a gitignore file
- Ignore pdf files
- Add a line with the pattern
*.pdfto your gitignore file and save it
- Add a line with the pattern
- Now look at
git statusagain. If everything worked, you should not see the changes in the pdf anymore, because it was ignored.
Compare commits
- Change some text in Bob.txt
- stage it with
git add - look at the diff with
git diff --staged - commit the changes
- compare this commit to the previous one with
git commit HEAD^
- push to origin
Merge your new branch with the main
If you want to locally integrate changes you did in a separate branch into the main branch, you first need to switch back to the main branch:
git checkout mainNow merge the commits from your branch with
git merge add_vegan_pieCheck if it actually worked with
git log