Exercise notebook: Git committing
-blue){kind=icon}
The notebook builds on our peer-reviewed pedagogical foundations.
We 
your feedback and suggestions on this notebook!
With this notebook, you can practice committing changes in Git.
| Practice | Label | Time (min) |
|---|---|---|
| 1 | Clone the repository | 5 |
| 2 | Create, stage, and commit changes | 10 |
| 3 | Undo committed changes | 8 |
| 4 | Create Atomic commits | 10 |
| 5 | Undo changes (advanced) | 5 |
| 6 | Wrap-up | 2 |
| Overall | 40 |
We are here to help if errors or questions come up!
Part 1: Clone the repository
In this part, we work with an existing project. To download the example, run the following commands:
cd /workspaces
git clone https://github.com/CoLRev-Environment/colrev
The clone command should print something like the following (the number of objects may differ):
```python Cloning into 'colrev'... remote: Counting objects: 100% (125/125), done. remote: Total 22225 (delta 41), reused 54 (delta 27), pack-reused 22100 Receiving objects: 100% (22225/22225), 10.11 MiB | 2.37 MiB/s, done. Resolving deltas: 100% (18519/18519), done. ```The repository has been downloaded to our machine (i.e., the Codespace environment). Let's enter the directory and to check the status.
Note: To create an empty git project, you would run git init.
code -a /workspaces/colrev
The status command provides an overview of the current state of the project and the files in the three sections. Therefore, you will need to run git status regularly.
Note: The comments after the hashtag (#) are ignored.
# Enter the directory of the colrev project
cd /workspaces/colrev
# Check the status of the project
git status
The `git status` command should print something like the following:
```python On branch main Your branch is up to date with 'origin/main'. nothing to commit, working tree clean ```The last line indicates that there are no changes in the staging area (nothing to commit). The working directory has the same content as the last version in the git repository (working tree clean).
Part 2: Create, stage, and commit changes
Next, we modify files (state: untracked/modified), mark them to be in the next commit (state: staged) and create the first version (state: committed). This corresponds to the three sections of a Git project.
Task: Open the README.md file in the colrev repository (shift + double click to open in a separate tab) and add your name to the project citation (# Citing CoLRev section).
# Check the `git status` between each command
git status
Task: Open the CONTRIBUTING.md file and change it.
The git status should now show two files with changes in the working directory (state: modified)
We decide that the changes in the README.md file should be staged for the next commit. The changes in the CONTRIBUTING.md file are no longer needed.
Task: Use the commands suggested by git status to accomplish this.
This means that changes in the README.md are staged (to be committed).
To commit the changes, we run
```python git commit -m 'add contributor' ```The -m 'add contributor' adds a short summary message, which is expected for every commit.
To undo the last commit, we can simply run:
```python git reset --soft HEAD~1 ```You should now have the README.md file in the staging area again.
Note: the HEAD~1 refers to the last commit.
Task: Run git status to see the changes.
We decide to discard our changes.
Task: Use the commands suggested by git status to do that.
## Part 4: Create atomic commits It is good practice to create atomic commits, i.e., small changes that belong together. One should avoid large commits that modify many unrelated parts of the code base and pursue different objectives.
Analyze the following commits and discuss which ones are atomic and which ones combine changes that do not belong together (i.e., should be in separate commits).
Also check the commit message (short summary at the beginning). Does the message clearly summarize the changes?
Commit 1It is ok to combine functionality, tests, and docs that belong together in one commit!
To create atomic commits, you may need to add specific lines of code that should go into a commit, leaving other changes in the working directory.
The changes are provided in the rec_dict.patch file, which must be placed in the project's working directory. To apply it, run:
Task: Use the Git GUI to check the changes that were introduced by the patch.
In the following, we would like to add only the changes in lines related to the load_records_dict method and the skip_notification parameter (using -p for a partial git add):
Task: Check whether the correct lines were added! Create a commit containing the relevant changes. Afterwards, discard the remaining changes.
## Part 5: Undo changes (advanced)To undo committed changes, there several options:
- Revert the commit, i.e., create a new commit to undo changes: `git revert COMMIT_SHA --no-edit` - Undo the commit and leave the changes in the staging area: `git reset --soft COMMIT_SHA` (*) - Stage changes, and run `git commit --amend` to modify the last commit (*)If you have the time, try the different undo operations in the session.
(*) Important: only amend commits that are not yet shared with the team. Otherwise, revert is preferred.
Even if you run
git reset --hard ..., you can still recover commits using git reflog. Committed data will only be lost permanently if you run git reflog expire --expire=now --all and git gc --prune=now --aggressive. If the commits are already on GitHub, you would need git push --force and the changes may also be synchronized in other local repositories. Avoid options like
--force, --hard, or --aggressive. Use them only if you know what you are doing. --- ## Wrap-up 🎉🎈 You have completed the Git commit notebook - good work! 🎈🎉 In this notebook, we have learned to - Clone a repository and check the `git status` - Create, stage, and commit changes using `git add`, `git commit` and `git restore` - Create atomic commits - Undo changes - Navigate VisualStudio Code on GitHub Codespaces Remember to delete your codespace [here](https://github.com/codespaces){: target="_blank"} (see [instructions](codespaces.ipynb)).