Instructor notes for the Git introduction lesson of the Software Carpentry.
The teaching style in these lecture notes has been derived from the Software Carpentry. The lecture notes make use of the Introduction to version control lesson material of software carpentry distributed under the CC By 4.0 license.
[12:45 PM - 13:00 PM] Opening
[13:00 PM - 13:20 PM] Creating a repository
[13:20 PM - 13:40 PM] Tracking changes: Modify, add, commit cycle
[13:40 PM - 13:50 PM] Break
[13:50 PM - 13:55 PM] Recap
[13:55 PM - 14:20 PM] Exploring history
[14:20 PM - 14:35 PM] Exercise
[14:35 PM - 14:40 PM] Exercise Q&A in plenum
[14:40 PM - 14:50 PM] Ignoring things
[14:50 PM - 15:00 PM] Break
[15:00 PM - 15:35 PM] Remotes in GitHub
[15:35 PM - 15:55 PM] Collaboration
[15:55 PM - 16:00 PM] Break
[16:00 PM - 16:20 PM] Conflicts
[16:20 PM - 16:35 PM] [Optional] Branches
[16:35 PM - 16:40 PM] Summary + where to go from here?
- Slides: Agenda, motivation, version control, git, goals, roadmap
-
Ojectives [1 min]
- How do I get set up to use Git?
- Use case description (Python code to convert fahrenheit to celsius)
- Where does Git store information?
-
Launch git bash [1 min]
-
Instructor sets up command history [2 min]
- On the primary terminal: Run the command
export PROMPT_COMMAND="history -a;$PROMPT_COMMAND"
- In a separate terminal, create an environment variable pointing to the file where the version history will be stored
- Make an empty directory, initialize with git, or clone the 4TU repository for workshop notes, and switch to a branch
- In the same terminal as above, run the command
tail -n 0 -f ~/.bash_history | tee $FILE
- Enable gitautopush to go through without asking for passphrase: start ssh agent with the command eval
ssh-agent.exe - Add and commit the history file and push once (Can I do this in advance?)
- On the primary terminal: Run the command
-
Configure git [3 min]
When we use Git on a new computer for the first time, we need to configure a few things. Below are a few examples of configurations we will set as we get started with Git:
- our name and email address,
- what our preferred text editor is,
- and that we want to use these settings globally (i.e. for every project).
git config --global user.name "name"
$ git config --global user.email "email address"Email address private?
- Create an empty directory [1 min]
mkdir convert_temperature
cd convert_temperature-
git repository [slide] [1 min]
-
git init [1 min]; explain what git init does
-
git status [1 min]
-
Evaluate progress [1 min]
-
Summary and Q&A [2 min]
-
Questions and objectives [1 min]
- How do I record changes in Git?
- How do I check the status of my version control repository?
- How do I record notes about what changes I made and why?
Note: We follow what git tells us to do till step 6. Instructor explains the concepts in step 7.
-
Create a python file named convert_temperature.py with the below code [2 min]
def fahrenheit_to_celsius(f): c = (f - 32.0) * (5.0/9.0) return c -
git status [1 min]
-
git diff [1 min]
-
git add [1 min]
-
Explain how git records snapshots. Explain Modify, add, commit cycle [slide] [2 min]
-
git commit + commit messages [2 min]
-
git log; Explain commit identifier, HEAD [2 min]
-
Summarize the above steps [1 min]
-
Progress checkpoint [2 min]
-
Repeat modify, add, commit cycle; add is name==main [2 min]
-
Summarize and Q&A [2 min]
****** 10 minutes Break ******
-
Objectives [1 min]
- How can I identify old versions of files?
- How do I review my changes?
- How can I recover old versions of files?
-
Modify file: alter temperature conversion formula [0.5 min]
-
git diff HEAD temperature.py [1 min]
-
git diff HEAD~2 temperature.py [0.5 min]
-
Recovering changes; recovering from 3 stages: working directory, staged, committed changes. [1 min]
-
git status: git restore options [1 min]
-
Restore file and bring back to same state as before. This is an example for reverting changes that are not staged. [1 min]
-
Make the same change again
-
Stage changes
-
git status -> git restore --staged to revert
-
do git restore --staged. This is an example of undoing changes that are staged but not committed.
-
make same change again
-
stage the change
-
commit the change
-
git status > shows empty status because nothing to commit or roll back.
-
git log
-
git show -> only way to spot if you did something wrong
-
When to explain HEAD
-
git checkout HEAD
1 convert_temp.py; Note: This operation brings the changes to the point HEAD1, then you stage and commit them as usual. Note that the earlier commit stays. -
stage and commit changes
-
git log
-
Summarize [2 min]
-
(Optional) Quiz in plenum
Link to exercise google doc: https://docs.google.com/presentation/d/17vM2uc_wvCcw7mVMqsNud71K_QZTlcXM4rD2DygkAtk/edit#slide=id.p
-
Answer Source: https://github.com/manuGil/lecture-notes/blob/main/git-notes.md Create new repository, use the modify-add-commit cycle, and recover older versions.
Create and initialize a repository called ‘my-repo’. $ mkdr my-repo $ cd my-repo/ $ git init -
Create a files research.txt with the sentence: Science is awesome
$ nano research.txt
- Inside the file type the following and save changes:
Science is awesome
- Add and commit the changes. Remember to use a meaning message.
$ git add research.txt
$ git commit -m "add awesome science"- Change sentence in ‘research.txt’ to: Science is messy
$ nano research.txt- Change text to this and save changes:
Science is messy- Add and commit.
$ git add research.txt
$ git commit -m "change to messy science"- Revert changes to the very first version of ‘research.txt’, and commit.
$ git log --oneline # find and copy ID of the firts commit
$ git checkout <commit-ID> research.txt # revert changes
$ cat reseach.txt # check version has been recovered
$ git commit -m "recover awesome science" # commit recovered version- Check your history log; you should have 3 commits
$ git log # print full log
$ git log --graph # print log as text-graph
$ git log --oneline # print short version of log-
Objectives and questions [1 min]
- How do I share my changes with others on the web?
- Explain what remote repositories are and why they are useful.
- Push to or pull from a remote repository.
-
Explain where remote repository fit in the scope of things using a picture (slide 25) [2 min]
-
Explain GitHub/GitLab [1 min]
-
Objective of typealong: Put our local changes on the internet to share with others.
-
Create an empty GitHhub repository [1 min]
-
Explain SSH [2 min]
-
Setup SSH [15 min]
Link to instructions: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
-
Connect the local repository with remote repoitory using git add remote origin command as shown after making the repository on GitHub + renaming branch to 'main' [1 min]
-
New command introduction: Git push [1 min]
-
Summarize [1 min]
Notes:
- Pull before you push
- Remote does not get updated with local changes automatically, you have to manually push your changes
- Keep remote up to date by pushing regularly.
-
Objectives [2 min]
- How can I use version control to collaborate with other people?
Version control with git really shines when used for collaborating. We learned how we can take our work from our computer to a repository on GitHub and others can see and download your code. We will now see how others can also contribute to your code.
- [Hands-on] Objective of typealong: Contribute changes to someone else's repsitory. [15 min]
For this step, get into pairs. One person will be the “Owner” and the other will be the “Collaborator”.
Plenum exercise:
- Learner adds their neighbor as collaborator on GitHub repository. Instructor shows how to do this via screen share. [2 min]
- Collaborator clones the repo and make changes, stage and commit locally. [2 min]
- Collaborator pushes changes to Owners github repo. [1 min]
- Owner updates their repository with collaborator's changes using git pull [1 min]
- If time permits, switch roles and repeat. [3 min]
- Summarize + Q&A [2 min]
Note:Contribute to a repository to which you don't have access to: Not covered today.
-
Objectives [1 min]
- What do I do when my changes conflict with someone else’s?
-
Conflict resolution demo [10 min]
- Instructor adds a helper as a collaborator in the repo.
- Helper adds an incorrect type hint or wrong print statement in if name==main.
- Helper pushes the code to owners repo
- Instructor makes a conflicting change locally and tries to push but the push is blocked due to conflict
- Instructor follows git's error message and does git pull
- Instructor sees that a conflict is reported by git and resolves it
- Instructor pushes the change
Tip: Read through SWC episode for correct reproduction of the conflict
-
Takeaway message [5 min]
Git’s ability to resolve conflicts is very useful, but conflict resolution costs time and effort, and can introduce errors if conflicts are not resolved correctly. If you find yourself resolving a lot of conflicts in a project, consider these technical approaches to reducing them:
- Pull from upstream more frequently, especially before starting new work
- Use topic branches to segregate work, merging to main when complete
- Make smaller more atomic commits
- Push your work when it is done and encourage your team to do the same to reduce work in progress and, by extension, the chance of having conflicts
- Where logically appropriate, break large files into smaller ones so that it is less likely that two authors will alter the same file simultaneously
- Motivation for branches: benefits, use cases
- Branches concept: parallel development line: use a diagram (code refinery diagram is good)
- Demo: helper makes a feature branch and pushes to the instructor's repository and creates a pull request. Instructor reviews the code and merges the changes.
- Pull request + code review (good practices)
- What did we learn today?
- Key takeaways
- Where to go next?