Collaborating
Last updated on 2024-03-05 | Edit this page
Estimated time: 25 minutes
Overview
Questions
- How can I use version control to collaborate with other people?
Objectives
- Clone a remote repository.
- Collaborate by pushing to a common repository.
- Describe the basic collaborative workflow.
Paper Writing
From the first episode!
Imagine you have 3 co-authors. How would you manage the changes and comments they make to your paper?
If you use Google Docs, you can have access to the history of changes, and also identify how made those changes.
For plain-text files, you can use GitHub to see the changes made per commit. In the left side or in color red are the deletions and in the right side or in color green the additions.
Additionally, in GitHub you can use the option Blame to
read the authors of changes per line. In this way, you can also read any
related comment regarding why an specific line was edited.
All of these is possible with a collaboration workflow between contributors using Git and GitHub!
Get a copy of remote
For the next step, get into pairs. One person will be the “Owner” and the other will be the “Collaborator”. The goal is that the Collaborator add changes into the Owner’s repository. We will switch roles at the end, so both persons will play Owner and Collaborator.
The Owner needs to give the Collaborator access. In your repository page on GitHub, click the “Settings” button on the right, select “Collaborators”, click “Add people”, and then enter your partner’s username.
To accept access to the Owner’s repo, the Collaborator needs to go to https://github.com/notifications or check for email notification. Once there she can accept access to the Owner’s repo.
Next, the Collaborator needs to download a copy of the Owner’s repository to her machine. This is called “cloning a repo”.
The Collaborator doesn’t want to overwrite her own version of
cases.git, so needs to clone the Owner’s repository to a
different location than her own repository with the same name.
To clone the Owner’s repo into Collaborator’s folder, in the Console, the Collaborator enters:
Replace ‘vlad’ with the Owner’s username.
Edit the clone
The Collaborator can now make a change in her clone of the Owner’s repository, exactly the same way as we’ve been doing before.
First, open the vlad-cases R project. If you are in
Rstudio: File > New Project... and navigate
to the directory location.
Now, let’s create a new file called dashboard.Rmd to
complement our Situation report!
R
usethis::edit_file("dashboard.Rmd")
OUTPUT
Let's create a dashboard!OUTPUT
1 file changed, 1 insertion(+)
create mode 100644 dashboard.RmdThen push the change to the Owner’s repository on GitHub:
OUTPUT
Enumerating objects: 4, done.
Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 306 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/vlad/cases.git
9272da5..29aba7c main -> mainNote that we didn’t have to create a remote called
origin: Git uses this name by default when we clone a
repository. (This is why origin was a sensible choice
earlier when we were setting up remotes by hand.)
Take a look at the Owner’s repository on GitHub again, and you should be able to see the new commit made by the Collaborator. You may need to refresh your browser to see the new commit.
In this episode and the previous one, our local repository has had a
single “remote”, called origin. A remote is a copy of the
repository that is hosted somewhere else, that we can push to and pull
from, and there’s no reason that you have to work with only one. For
example, on some large projects you might have your own copy in your own
GitHub account (you’d probably call this origin) and also
the main “upstream” project repository (let’s call this
upstream for the sake of examples). You would pull from
upstream from time to time to get the latest updates that
other people have committed.
Remember that the name you give to a remote only exists locally. It’s
an alias that you choose - whether origin, or
upstream, or fred - and not something
intrinstic to the remote repository.
The git remote family of commands is used to set up and
alter the remotes associated with a repository. Here are some of the
most useful ones:
-
git remote -vlists all the remotes that are configured (we already used this in the last episode) -
git remote add [name] [url]is used to add a new remote -
git remote remove [name]removes a remote. Note that it doesn’t affect the remote repository at all - it just removes the link to it from the local repo. -
git remote set-url [name] [newurl]changes the URL that is associated with the remote. This is useful if it has moved, e.g. to a different GitHub account, or from GitHub to a different hosting service. Or, if we made a typo when adding it! -
git remote rename [oldname] [newname]changes the local alias by which a remote is known - its name. For example, one could use this to changeupstreamtofred.
Download contributor edits
To download the Collaborator’s changes from GitHub, in the Console, the Owner now enters:
OUTPUT
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/vlad/cases
* branch main -> FETCH_HEAD
9272da5..29aba7c main -> origin/main
Updating 9272da5..29aba7c
Fast-forward
dashboard.Rmd | 1 +
1 file changed, 1 insertion(+)
create mode 100644 dashboard.RmdNow the three repositories (Owner’s local, Collaborator’s local, and Owner’s on GitHub) are back in sync.
A Basic Collaborative Workflow
In practice, it is good to be sure that you have an updated version
of the repository you are collaborating on, so you should
git pull before making our changes. The basic collaborative
workflow would be:
- update your local repo with
git pull origin main, - make your changes and stage them with
git add, - commit your changes with
git commit -m, and - upload the changes to GitHub with
git push origin main
It is better to make many commits with smaller changes rather than of one commit with massive changes: small commits are easier to read and review.
On GitHub, the Collaborator can go to the repository and click on “commits” to view the most recent commits pushed to the repository.
On the command line, the Collaborator can use
git fetch origin main to get the remote changes into the
local repository, but without merging them. Then by running
git diff main origin/main the Collaborator will see the
changes output in the terminal.
git fetch to download the
remote content but not update your local repo’s working state, leaving
your current work intact. Use git pull to download the
remote content for the active local branch and immediately merge it.
this can potentially cause conflicts.Group challenge
Individual challenges
To create this, go to the GitHub Home
page, identify the section called Introduce yourself with a
profile README. Click on Create:
Edit the lines in the template file. Then click on
Commit changes...
To edit this in a local repository, clone it following the steps you learned!
Comment Changes in GitHub
The Collaborator has some questions about one line change made by the Owner and has some suggestions to propose.
With GitHub, it is possible to comment on the diff of a commit. Over the line of code to comment, a blue comment icon appears to open a comment window.
The Collaborator posts her comments and suggestions using the GitHub interface.