Introduction to Git & GitHub
Before we start
- Does everyone have a GitHub account created?
- Does everyone have Git installed on their computer?
- We will be using the Command Line Interface version of Git, not the GUI. (because Sam doesn't know the GUI - not because it isn't great).
- Who has used Git before? Why? How?
GitHub and social coding
Git is a way to share, edit, and discuss code. GitHub makes this so much easier. There are a lot of major and minor projects tracked with Git, like Linux, Apple's Swift language, and even this Maptime Seattle website.
Before we start, it's important to remember:
Git is an active workflow.
There are many ways to accomplish the same thing with Git & GitHub.
Our goals today:
- Open the Git Dictionary
- Git on the command line
- Tutorial: personal workflow
- Tutorial: branching
- Tutorial: fork & pull
- Tutorial: merge conflicts
- Introduce GitHub pages (if time permits)
Git vocabulary quest
For the majority of this tutorial, I'll reference Git & GitHub interchangably. They are very different, but I'm tired of constantly saying "Git and GitHub".
- Git: version control software that can be installed on your computer. It comes with a command line interface accessed with the
gitcommand. Git tracks line changes in your code (added a line, changed a line, removed a line). This means it doesn't track binary files well!
- Version control: recording changes in history. Everything from new lines to new files.
- Command line interface (CLI): the Neo's Matrix part of your computer, a textual representation of the contents of your local computer
- GitHub: a private company that has built a web interface for Git-based projects and introduced a much more community-oriented means of writing and discussing programming projects.
- Permissions & organizations: each GitHub repository is typically under your username or an organization's name (a collection of GitHub users). Only people with persmission to edit code are allowed. You can always edit the code in your own repository.
- Repository: a project on GitHub
- Local: your computer and the contents on it
- Remote: the non-local store for your project's files (typically a GitHub repository, but can be other things like a private server). You can have multiple remotes, but the standard is to name your primary remote
- Fork: a copy of another project, allowing you to make edits without touching the original project. This copies from the original remote into a new remote on GitHub.
- Clone: a direct clone of a project on your local computer. You can clone any repository (even if you don't have the proper permissions, but you won't be able to make changes to the project's remote if you don't have permissions).
- Branch: a specific "scope" of your project. The "main" branch is typically referred to as
master. You can have an infinite number of branches to avoid making changes to master.
- Commit: a summary of a number of edits to a project, marked as a single node in a Git history
- Push: put all of the commits you have on your local to your remote
- Pull: grab all of the recent changes to a remote project that you don't have on your local computer.
- Pull request: request another repository or project (that you do not have permissions to edit) to pull in your changes (series of commits).
- Issue: A GitHubian way to track bugs, ideas, thoughts, and conversation.
- README: The first file every repository should include, describing what the project is, how to use/install it, and how to contribute.
- Markdown: the standard formatter for writing text on GitHub.
Tutorial Specific Dictionary
- geojson.io: a nifty website for creating GeoJSON.
- Rabbit hole: a place where you all hopefully take us down by asking awesome, crazy questions. Interuptions are totally allowed. Ask away!
Introduction to the command line
Git workflow: personal
- Create a personal project on GitHub (name it whatever you want)
- Open your command line and clone the new repository onto your local computer
git clone repo
- Add a new file called
README.mdand write something
- Check the status of your Git project with
- begin tracking the new file in Git by adding it.
git add README.md.
- Check the status again to see the difference
- Commit the file with
git commit -m 'your message'
- Push the changes to your remote with
git push origin master.
You'll notice changes on your GitHub page! But what if you didn't want to push changes directly into the
master branch? What if you were experimenting with something new and wanted to push it up to GitHub for someone to see, but not commit directly to the main project?
Git workflow: branching
- Back to your local computer, create a new branch with
git checkout -b new-branch-name. This command
-bcreates a new branch AND checks it out.
- You can list all branches and see which branch you are currently on with
- Make some changes and add those changes with
git add README.md(or if you are adding a new file)
- Commit those changes with
git commit -m 'my cool new feature experiment'
- Push those changes to a new branch on your remote with
git push origin new-branch-name
- Create a pull request on GitHub and write up the changes you made!
In an organizational setting, this will notify project maintainers of your changes and give everyone a chance to review and comment on the pull request. Others can pull this code into their local, make changes, and push up to the same branch, which will update the pull request accordingly.
Git workflow: fork and pull
Sometimes you won't have the ability to add a new branch to a project because you aren't listed as a maintainer. You can still contribute!
- Fork a repository you want contribute to
- Clone your fork to your local machine
git clone https://...
- Make changes
- Push up to your remote fork
- Go to the main repository and create a pull request from your fork into the main project (you won't be able to merge this, only a maintainer can merge)
Let's try this same workflow with the maptimesea
geojson repository. Follow the steps here: https://github.com/maptimesea/geojson#geojson
Fixing a merge conflict
Remember, Git is active! If things are broken, you've gotta fix them. Most of the time, this comes down to "merge conflicts". This typically means the code that you have doesn't match the changes of the code in a remote, and if you were to merge your code in, you'd lose someone elses work. The best way to learn how to fix a merge conflict is to see one, and try fixing it.
With the same geojson repository fork, add a location the
EVERYBODY.geojson file and make a pull request again. This time, we'll all be adding to the exact same file, insted of unique files.
Depending on which pull request is merged first (before yours), you'll likely see a message from GitHub that your fork cannot be automatically merged into the MaptimeSEA repository because it is missing commits. Here's how to remedy:
- Get all of the changes from the primary repo (called
git fetch upstream
- Merge all of the upstream
masterbranch changes into your fork's
git merge upstream/master.
- You may see a merge conflict! That's okay - we can fix this. Open
EVERYBODY.geojsonand you'll notice some odd lines like
>>>>>>>> heador something similar. This is showing you what the primary file looks like, and what your current file looks like, and why they can't be automatically merged.
- Manually fix the file to include all additions to the GeoJSON file (This is where being active and intentional about your code is important. It is up to you to know what code should be included).
- Once updated, run
git add EVERYBODY.geojson
- Commit the file again
git commit -m 'fixing merge conflicts'
- Push to your fork's master branch
git push origin masterand you'll see the pull request automatically update with your changes.