clean-code
Training materials and slides for courses on version control, clean code and documentation with practical examples and exercises in Python and R
Git(Hub) core concepts
Repository
A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.
From GitHub glossary/repository
Task 3: Create a repository on with the Github web-interface
- read the documentation on how to create a new repository with the GitHub web-interface
- create a new public “test”-repository and include a README file with the web-interface
Commit
A commit, or “revision”, is an individual change to a file (or set of files). When you make a commit to save your work, Git creates a unique ID (a.k.a. the “SHA” or “hash”) that allows you to keep record of the specific changes committed along with who made them and when. Commits usually contain a commit message which is a brief description of what changes were made.
Task 4: Commit to a repository with the GitHub web-interface
- add some text to the README file and commit the changes with the GitHub web-interface
Clone
A clone is a copy of a repository that lives on your computer instead of on a website’s server somewhere, or the act of making that copy. When you make a clone, you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. The repository you cloned is still connected to the remote version so that you can push your local changes to the remote to keep them synced when you’re online.
Task 5: Sign in to GitHub Desktop
- read the documentation on how to sign in to GitHub Desktop
- sign in to GitHub Desktop
Task 6: Clone a repository with GitHub Desktop
- read the documentation on how to clone a repository with GitHub Desktop
- clone the “test”-repository with GitHub Desktop
Push
To push means to send your committed changes to a remote repository on GitHub.com. For instance, if you change something locally, you can push those changes so that others may access them.
From GitHub glossary/push
Task 7: Push a commit to remote with GitHub Desktop
- open the README file on the local “test”-repository, add some text, and save the file
- read the documentation on how to commit and push your changes with GitHub Desktop
- commit your changes to the “main”-branch of the “test”-repository with GitHub Desktop
- push your changes to the remote “test”-repository with GitHub Desktop
Branches
A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or main branch allowing you to work freely without disrupting the “live” version. When you’ve made the changes you want to make, you can merge your branch back into the main branch to publish your changes.
Task 8: Create a “new”-branch with the GitHub web-interface
- read the documentation on creating branches with the web-interface
- create a branch called “new” with the web-interface
Task 9: Commit to “new”-branch with the GitHub web-interface
- read the documentation on viewing branches with the web-interface
- commit a new TXT file called “hello.txt” to the “new”-branch with the web-interface
Pull
Pull refers to when you are fetching in changes and merging them. For instance, if someone has edited the remote file you’re both working on, you’ll want to pull in those changes to your local copy so that it’s up to date.
From GitHub glossary/pull
Task 10: Switch to “new”-branch with GitHub Desktop
- read the documentation on switching branches with GitHub Desktop
- switch to “new”-branch with GitHub Desktop
Merge and pull requests
Merging takes the changes from one branch (in the same repository or from a fork), and applies them into another. This often happens as a “pull request” (which can be thought of as a request to merge), or via the command line. A merge can be done through a pull request via the GitHub.com web interface if there are no conflicting changes, or can always be done via the command line.
Task 11: Merge “new”-branch into main via a pull request
- read the documentation on creating a pull request with GitHub Desktop
- create a pull request from “new”-branch into “main”-branch with GitHub Desktop
- read the documentation on merging pull requests with the web-interface
- merge the pull request with the web-interface
Task 12: Delete the “new”-branch with the GitHub web-interface
- read the documentation on deleting branches with the web-interface
- delete the “new”-branch with the web-interface
Optional tasks
Task 13: review a pull request
- read the documentation on pull request reviews
- pair up with one of your peers from this course
- clone their “test”-repository
- change a file and make a pull request
- review their pull request to your “test”-repository
Task 14: create and resolve a merge conflict
- read the documentation on merge conflicts
- create a merge conflict in your “test”-repository
- try to resolve the merge conflict