Introduction to Git and GitHub
https://ubc-library-rc.github.io/intro-git/
The goal of this workshop is to show you the basic commands in Git and Github so that you can start to use it
to track your projects. This workshop only introduces a few features of Git. This session is prepared for you, so if you
have questions or feel the pace is not aligned with your level, please let us know.
Land Acknowledgement
UBC Vancouver is located on the traditional, ancestral, and unceded territory of the xʷməθkʷəy̓əm (Musqueam) peoples.
But before going into more details I would like to begin by acknowledging that I am fortunate to present this workshop in Burnaby which is the unceded territory of the Coast Salish People.
Use the Zoom toolbar to engage
Participants window
Active participation makes the session so much fun and gives me and your peers much more energy. We are
all sitting in our offices with little sound. Your voices and perspectives enlivens the session. We encourage
you to engage with each other and instructors.
The participants window lists everyone in the session and click the icons at the bottom to communicate with
the instructors.
You can also use the Chat windows to comment or ask questions at any time. It is also a good place to share
problems with your audio connection.
For the next slide, use the annotation toolbar on the top of the screen.
I have never used the command line
I use the command line often
To get a better idea of your familiarity with the command line, please answer to this question by
putting a mark on the spectrum somewhere between I have never used the command line and I use the command line
often.
Choose what to do based on their answer.
Learning Objectives
Create a Git repository on their local machine and track changes
Create a remote repository on Github
Link a local Git repository to a remote Github repository and sync changes
List Git and Github features for project development and team collaboration
Pre-workshop setup
Install Bash Shell and Git
Create a free Github account
For more information, check out Pre-workshop setup
Please make sure to have a Bash Shell and Git installed before the workshop.
If you do not have access to a laptop or have difficulty meeting these prerequisites please contact shayanfa@mail.ubc.ca. We will do our best to ensure everyone can participate.
1. Create a free GitHub account
2. Install the Bash Shell and Git
Mac and Linux. Bash is already installed.
Install Git using these instructions.
If you use macOS Catalina or newer versions, change the default shell to Bash by running the following command:
Open Bash (Terminal in Mac, Git Bash in Windows) and enter the following commands to configure Git. (Note that $ represents the command prompt; the commands themselves start with the word git.)
What is version control?
Version control software tracks the changes made to a group of files. Version control systems like Git are often associated with software development but are increasingly used for collaboration in research and academic environments..
The most important reason is that you do not want to end up in this familiar place.
Version control can be used to keep the history of changes in the file, and you can use it to undo changes or
version your files
Benefits of version control
collaboration
versioning
rolling back
understanding context
backup
But the benefit is not just that.
It takes some discipline to learn and make use of version control but there are many benefits:
Collaboration - Version control helps teams work collaboratively on same set of documents without interfering with each other.
Versioning - It provides a thorough log of changes to tracked files without creating multiple copies, making it easier to identify the most current version.
Rolling back - Made a mistake? Version control lets you review and undo changes, reverting to previous stages in the document’s history. This can be useful when changes to your files introduce unforeseen problems.
Understanding context - Version control can help you understand how the code or writing came to be, who wrote or contributed particular parts, and who you might ask to help understand it better.
Backup - While not meant to be a backup solution, version control systems mean your code and writing can be stored on multiple computers.
Git: open source tool installed on your local computer to track changes made to a set of files (referred to as a git repository )
GitHub: a popular website for hosting and sharing Git repositories
Git and GitHub are often used interchangeably but it’s important to understand what each does and how they work together.
Git is a free, open source tool that can be installed on your local computer to track changes made to a set of files (referred to as a “git repository” or “repo”). Git can be used independently to organize one’s own work, or to coordinate team projects with multiple authors. Git ensures that everyone’s contributions are tracked and merged effectively by keeping copies of all previous versions and documenting the changes, when they were made, and by whom.
Git was designed for text files that can be opened in a text editor (as opposed to binary file formats like .pdf and .docx). A Git repository can preserve files of any type, but only text files will benefit from all Git’s features.
GitHub is a popular website for hosting and sharing Git repositories. GitHub provides online infrastructure that makes it easier for teams to collaborate with Git. Team members make contributions to the repository on local copies of the files, then “push” their changes back to GitHub so everyone else can see them.
The GitHub interface makes it easy to view files in the repository and what changes have been made. GitHub also makes it easier for groups to publish their work (each GitHub repository can have its own project website, blog, and wiki using GitHub Pages.)
Some Linux commands
$ cd [directory-name]
$ mkdir [new-directory-name]
$ ls
$ touch [file-name]
We need to know a little bit about the terminal to be able to explore and use the features of Git.
To navigate betwen files and directories within a system. You can either use the full path of the relative directory name
cd ..
mkdir to make a new directory
ls to list files and directories within a system, ls -a also lists hidden files.
touch makes an empty file in the current directory
and cat read files and writes them on the screen.
Git Workflows
Making and maintaining a repository on your machine
Creating a repository on Github
Syncing local repository with Github
Forking projects and working collaboratively
Creating a repository
$ mkdir hello-world
$ cd hello-world
$ git init
You can think of a repository as a group of files that Git tracks. When you create a repository Git generates a hidden directory named .git in the same folder. Information about the repository, changes to the files, and previous versions are all stored in this hidden directory so they are accessible but don’t get in the way.
You can create repositories using GitHubs web interface, or on your own computer using the command line. Let’s use the command line to create a Git repository for new project. (On a Mac, open Terminal, on a PC open Git Bash.)
First, create a directory called hello-world and navigate to the new directory.
We will now create a Git repository to track changes to our project. Use the git init command, which is simply short for initialise.
If you run the “ls” command to list the contents of the “hello-world” directory your repository may seem empty. But running “ls -a” instead will include hidden files in the list, revealing the new hidden directory named “.git”.
Displaying project status
$ git status
The git status command displays the current state of a project.
The output introduces two new Git concepts:
branch main. A Git repository can be split into multiple “branches” that can be worked on independently before merging later. New repositories start with only one branch, named “main” by default. In this workshop everything we do will be in branch main.
commit. The git commit command saves your changes to the repository. The output above tells us there is nothing new to save in our repository.
Git Workflow on your local machine
We will now create and save our first project file. This is a two-stage process. First, we add any files for which we want to save the changes to a staging area, then we commit those changes to the repository. This two-stage process gives us fine-grained control over what should and should not be included in a particular commit.
Lets create a new file using the touch command, which is a quick way to create an empty file.
Lets check the status of our project: Git has noticed a new file in our directory that we are not yet tracking. With colourised output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to index.md, we use git add.
Git commands
This adds the file to the staging area, telling Git that “index.md” is a file it should track. To see what effect this had we can use git status again.
Before committing the new file, open “index.md” in a text editor, add a line of text, then save the file. (In this example we enter the text Hello, world!). Use git status to see what has chnaged from Git’s perpective.
This lets us know that Git has indeed spotted the changes to our file, but that it hasn’t yet staged them, so let’s add the new version of “index.md” to the staging area.
Now we are ready to commit our first changes. Commit is similar to “saving” a file, but in addition to saving the contents of a file git commit stores information about the file’s history, including what changes were made, when, and by whom.
Having made a commit, we now have a permanent record of what changed, along with information about who made the commit and at what time.
Diff and log command
$ git diff
$ git diff HEAD
$ git log
The git diff command shows the changes we have made before a commit. To test this, open “index.md” with any text editor and enter a new line of text (in this example we added “It’s a beautiful rainy day” on the second line of “index.md”). Save the file, then use git diff to see the changes.
Heres what the output reveals:
Line 1 tells us Git is comparing “a” and “b” versions of the index.md file
Line 2 indicates which tracked versions “a” and “b” correspond to; “aed0629” and “989787e” are unique computer-generated identifiers for each version
The last two lines show the changes to the “index.md” between the compared versions:
there were no changes to the # Hello, world! line
a line was added with the text It's a beautiful rainy day (“+” indicates an addition and “-“, a deletion)
Git branches
$ git branch
$ git branch new-feature
$ git checkout new-feature
Git branches allows you to work on different parts of a project collaboratively without impacting the main branch. When the work is complete, a branch can be merged to with the main project. Each branch is a separate version of the main repository.
Other features
.gitignore
Why staging is useful
Undoing changes in Git
Git tags
Github repositories
https://github.com/
So far you used Git to create a repository called “hello-world” on your own computer, but no one else can see those files. Next you will use GitHub to share the contents of your repository so others can collaborate. This involves creating an empty repository in GitHub, then linking it to your local repository.
Make an empty repository, talk about the readme file, clone the repository on your local machine, add the files, push it to Github, change it on Github, pulling on the local machine
After creating the “hello-world” repository GitHub will display the repository page. This includes information required to link your GitHub repository to the “hello-world” repository you created with Git on your own computer.
link the repositories with “git remote add” Enter the command below, replacing as appropriate.
Linking your local repository to Github
You have two options to connect your local machine to Github. SSH is a security protocol widely used by many application. You can use the following commands to connect your newly created repository or your existing repository to Github.
You can also use HTTPS protocol to connect your local repository to Github. Take a look at the following figure and find the commands you need to use to sync your local repository with Github. We will explain these commands in the rest of this section.
Github removed password authentication on August 13, 2021. SSH is a secure way to connect your local machine to Github. To use the SSH protocol, we need a little more setup before we can actually connect to the remote repository.
In this workshop, we are going to use the HTTPS protocol and Github access tokens. The latter is simpler but should be used with cautious.
Git remote
$ git remote add origin https://github.com/[your_github_username]/[github-repository-name].git
$ git remote -v
This links your local Git repository to a remote one. The link indicates the location of the remote repository, which is nicknamed origin in this example. The nickname can be anything but Git convention is to refer to the remote repository as “origin”.
We can confirm that it is set up correctly with this command:
HTTPS connection to remote
Configure access token on Github
$ git remote set-url origin https://[github-token]@github.com/
[your_github_username]/[github-repository-name].git
You can use token-based authentication when performing Git operations requiring authentication.
In the first step, we will create a personal Access Token on Github. Follow these steps for create one for your Github account:
Click on your Github profile icon on the top right corner and click on Settings
Choose Developer Settings on the menu on the left
Click Personal access tokens and Generate new token]* Add a specific note that will help you identify the scope of the access token
Choose the Expiration period from the drop down menu and select the scopes you want to grant the corresponding access to the generated access token. Make sure to select the minimum required scopes. For this workshop, public_repo should be enough.
Click on Generate Token
Now, a new page is openned in which you can see your personal access token and copy it.
Now, we need to run the following command to use this access token:
Git push and pull
$ git push -u origin main
$ git pull
The git push command can “push” our local content and tracking information to the GitHub repository, synchronizing the content.
When working with others or on multiple computers we need a way to pull all the remote changes back into our local repository. We can see how this works by adding a file to our GitHub repository, then “pulling” that change back to our computer.
Near the bottom of the “hello-world” repository on GitHub there is a button to “Add a README” file to your repository. Click the button, enter some text, then scroll to the bottom and click “Commit new file” (The default commit message will be “Create README.md”, which is fine for our purposes).
It is good practice to add a README file briefly describing what the project is about. If the README is in the root directory GitHub will automatically display it like a cover page for your repository.
After adding a README on GitHub your local repository is out-of-sync with the remote repository. Let’s fix that by pulling the remote changes into local repository with git pull.
Collaboration on GitHub
Collaboration on GitHub
Git and open source community
Hacktoberfest is a month-long celebration of open-source software by DigitalOcean that encourages participation in giving back to the open-source community.
Github is a great resource for programmers and enthusiasts. Many open-source projects are hosted on Github. Among them, you can find [Linux](https://github.com/torvalds/linux), [Tensorflow](https://github.com/tensorflow/tensorflow), and [Windows Terminal](https://github.com/microsoft/terminal). You can even find riginal code for [Windows Calculator app](https://github.com/microsoft/calculator) on Github.
Github hosts millions of open-source projects. With open-source projects, people on different skill levels can work to make technologies more accessible or build meaningful resources for communities. Learning how an open-source software is built and maintained can be a great programming class as well.
If you would like to participate in open-source projects on Github, October is the perfect month. [Hacktoberfest](https://hacktoberfest.com/) is a month-long celebration of open-source software by DigitalOcean that encourages participation in giving back to the open-source community. Developers get involved by completing pull requests, participating in events, and donating to open source projects.
Github features
Github also has many great features that support project development and management. Here, you can find a list of those features and some notes on collaborating with other teams members on Github.
* **Github issues** let you track your work on Github. When you mention an issue in another issue or pull-request, the issue's timeline tracks the related work. You can link issues to pull requests.
* **Gist code** is a simple way to share code snippets with others. It is used when you need to share a sample piece of code or technique with your co-workers or friends. To learn more Github Gists and how to create them, check out [Github Tutorial on Creating Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists)
* **Project management with Github** is possible is Github offers a card-based project management tool like the one offered by [Trello](https://trello.com/). To begin the setup process, you should click on the **projects** tab in your repository and select **create a project**. Github offers templates to organize tasks within the project workflow. You can also set automatic triggers and link them to Github pull requests.
* **Github Wiki** is a feature on Github to host the documentation of the repository. You can edit wikis directly on Github or edit wiki files locally. Github Docs give you more information about [Github Wikis](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis).
* **Github Pages** is a static site hosting website that takes HTML, CSS, and JavaScript files straight from a repository on Github and publishes a website with them. To learn more about this feature, you can check [Github Docs](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) or the [Introduction to Jekyll](https://ubc-library-rc.github.io/intro-jekyll/) workshop.
A sandbox repository
Link to the repository
In this exercise, you are going to use Git and Github to fix mistakes in a repository. You can download the `sandbox` repository here: [address](address)
This repository supposed to have two folders. In the folder `text`, we would like to keep pieces of news as text files. In the second folder, `figures`, we would like to keep on figure for each file. The whole repository is a simplified version of a database for the news website.
There are some mistakes in the repository, such as files with wrong extensions, and some minor mistakes, such as mistakes in spelling of words. You are asked to add one more piece of news or fix the repository either directly on Github or by pulling the local repository, fixing the problems, and pushing it to the remote repository.
Git and Visual Studio Code
Try it out!
Instructons in Git basics section of sitehttps://ubc-library-rc.github.io/intro-git/
