Working together online on GitHub¶

You may want to develop code online with other collaborators. In this case, GitHub is a really great tool. Let's go through a workflow here

Let's say you have a piece of code you're working on and you have made changes. You're happy with your changes so you use the following to add the changes, commit them, and push them to GitHub

git add .
git commit -m 'My new commit'
git push

git clone¶

If I'm also working on the same tool, I might want to get your work. I can do this using the git command on my terminal

git clone https://github.com/your_username/your_tool.git

This will create a new directory with all your work in it.

git pull¶

After a few days, you might have put some more commits in your online repo, and I'm going to want to get them too. So I will get those changes with

git pull

If I try to push to a repo (assuming I have permission to do so), sometimes there will be a conflict, and I'll need to pull changes down first before it will let me push my own changes with git push.

Pull Requests¶

"Pull request" here means "I am a developer, and I request you pull my changes into your code".

If you're working together, pull requests on GitHub are great. They are a way for a user to suggest changes to your code. I open PRs against my own code, because they're a great way to document major changes.

If you have a repo, and I want to suggest some changes to it, I might follow this workflow. If I have permission to work with your repository on GitHub (because you've given me permission, or because I'm part of the organization that made the repository) I could do this:

git clone https://github.com/your_username/your_tool.git
git checkout -B my-new-branch
...
# Make some changes to files
...
git add .
git commit -m 'christinas awesome fix'
git remote add origin https://github.com/my_username/your_tool.git
git push --set-upstream origin main

This will make a new branch called my-new-branch on GitHub. From there I can open a pull request. GitHub will even prompt you with a Compare and Pull Request button. Below is an example of what a pull request looks like.

The example here is a tool that I've written, that a collaborator would like to open a pull request against. They've made changes on a branch named tiled-query and opened a PR. Here are some of the key things to note

1. There is a space for discussion. We can talk about the good and bad points of the PR, and discuss changes.
2. You can see the commit history, and the files that have changed in the PR
3. If you have GitHub actions with tests enabled, those will run and check the PR (see a later section for more on that)
4. You can request reviews (top right) assign people who should be looking at the PR, and label the PR with handy tags like "easy" or "bug".

When someone opens a PR on one of my repos, I will usually review it, and check that I agree with the changes they are proposing. We'll discuss on the PR, and come to an agreement. Then, if we think it needs to be included in the main branch, we will merge the pull request. This will put all the changes into the main branch. You should only do this when all your tests are passing and you are happy, but in theory it is possible to undo this action.

Pushing to main¶

Sometimes our packages break. Maybe one of our dependencies is broken, or maybe someone has merged a pull request that shouldn't be merged. If I'm a core developer of a package, and if there's a sudden issue, sometimes I might make changes to the code, and instead of going the careful route of opening a PR and having the team review it, I will push directly to the main branch. This is living a little dangerously, as pushing straight to main without a review could cause an error. Use this with caution, it's better to open PRs and review changes before merging them.

Forks¶

Sometimes I won't have permission to work on your GitHub repo, because you won't know me. In those cases, I might still want to work on your code. In such a case, I can use a fork. Repos on GitHub have a fork button in the top right corner.

This will make a copy of the repo in your GitHub account. Instead of pushing to the copy living at the original URL

https://github.com/your_username/your_tool.git

Now I will be pushing to the copy at this URL

https://github.com/my_username/your_tool.git

This time, your workflow will be like this

git clone https://github.com/my_username/your_tool.git
git checkout -B my-new-branch
...
# Make some changes to files
...
git add .
git commit -m 'christinas awesome fix'
git remote add my-fork https://github.com/my_username/your_tool.git
git push --set-upstream my-fork main

Now I'm pushing not to your GitHub URL, but to my forked version. I can now open a PR against your original repo in the same way, and follow all the instructions above!

I still have to be careful that there is an original repo, which may have some changes that I also want while I'm working on my version. To keep up to date you will want to 1. add a remote which tracks the original repository

git remote add origin https://github.com/your_username/your_tool.git

and then 2. I will want to fetch that repository, so I have access to all your possible branches.

git fetch origin

and finally 3. I will want to sometimes pull from the branch that you are working on so I can keep up to date with all your changes. Below I'm pulling the main branch from origin

git pull origin main

Merge conflicts¶

Whenever you do a pull action in git or on GitHub, git tries to automatically merge the files that have changed. Sometimes it can't and it will raise a "merge conflict", which means that it doesn't know which changes are the ones it should carry forward.

If you find you have a merge conflict, git will stop your merge and ask you to resolve them. You can do this by going into the file with the conflict, and looking for the place where there is a conflict. This will be highlighted using the syntax below

<<<<<<< HEAD
current change
===========
change that would be merged
>>>>>>>>>>>

If you find a conflict, simply pick which of these changes are correct, and then continue with the merge.