Git Joys: Collaboration

In the previous post we ran through a concrete example of Git, but it was very simple and assumed we were not going to be collaborating with anyone else. This time we do something more powerful and collaborate with others. We will be using the MAVProxy GitHub repository. I am doing this on Ubuntu 18.04.

There are two major protocols Git uses to to facilitate collaboration: ssh or SSL. I will delve into both in this section, but materials are all over the Internet on this so I will keep my descriptions brief. Before we begin create the following directories directories from the shell:

mkdir MAVProxy-ssl
mkdir MAVProxy-ssh

SSL

I will first do SSL as it is arguably the simpler of the two. First change into the MAVProxy-ssl directory.

cd MAVProxy-ssl

Then point your favorite browser to github.com. I recommend creating an account if you haven’t already done so, but MAVProxy provides read access to their repository (as do many repos on GitHub) so this is not strictly necessary if you prefer no to. You will find a page that looks more or less like this:

Click on the green button in the center that says “Code.” Clicking on “HTTPS” will bring up the following dialog box:

which will allow you to download the repository via the HTTPS (SSL) protocol. Now enter the at the prompt (but DO NOT hit return yet):

git clone

Copy the URL https://github.com/ArduPilot/MAVProxy.git (from the above dialog box in the image) and paste it into the text following git clone:

git clone https://github.com/ArduPilot/MAVProxy.git

If successful you should see (the numbers will be somewhat different):

Cloning into 'MAVProxy'...
remote: Enumerating objects: 76, done.
remote: Counting objects: 100% (76/76), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 15704 (delta 46), reused 39 (delta 22), pack-reused 15628
Receiving objects: 100% (15704/15704), 62.91 MiB | 44.43 MiB/s, done.
Resolving deltas: 100% (11265/11265), done.

Voila! You have successfully cloned the MAVProxy repo with SSL. Let’s try it now via SSH.

SSH

Please note: the following requires you to create an account with github.

Start by changing into the MAVProxy-ssh directory:

cd MAVProxy-ssh

Follow these instructions to set up a public and a private SSH key for github.

Pro Tip: It is very risky to leave your private key without a password.

Then point ssh-agent at it using this bash script (e.g., by putting it in your $HOME/.bashrc file):

SSH_ENV=$HOME/.ssh/environment
function start_agent {
echo "Initializing new SSH agent..."
/usr/bin/ssh-agent | sed 's/^echo/#echo/' > "${SSH_ENV}"
chmod 600 "${SSH_ENV}"
. "${SSH_ENV}" > /dev/null
/usr/bin/ssh-add
}
if [ -f "${SSH_ENV}" ]; then
. "${SSH_ENV}" > /dev/null
ps -ef | grep ${SSH_AGENT_PID} | grep ssh-agent$ > /dev/null || {
start_agent;
}
else
start_agent;
fi

Pull up the browser to the MAVProxy page and again click in the “Code:” section. Click on the SSH section:

Now enter the at the prompt (but DO NOT hit return yet):

git clone

Copy and paste git@github.com:ArduPilot/MAVProxy.git (from the above dialog box in the image) and paste it into the text following git clone:

git clone git@github.com:ArduPilot/MAVProxy.git

Which should yield:

Cloning into 'MAVProxy'...
remote: Enumerating objects: 76, done.
remote: Counting objects: 100% (76/76), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 15704 (delta 46), reused 39 (delta 22), pack-reused 15628
Receiving objects: 100% (15704/15704), 62.91 MiB | 51.09 MiB/s, done.
Resolving deltas: 100% (11265/11265), done.

Superb! You have successfully cloned the MAVProxy repo with SSH!

GitHub CLI

The GitHub CLI is relatively new and frankly I’m unfamiliar with it at the time. It is documented here.

Your First Pull Request

Creating a pull request is documented on GitHub, but I am going to walk you through a full-fledged example.

Forking A Repository

Creating your own copy of a repository at a certain snapshot in time is known as forking. Let’s try it now by clicking the Fork button:

If the repository has not already been forked then it should begin the forking process. Then you will be presented with this screen:

Note the mday299 (my GitHub user name) where ArduPilot had been before

Because I just forked the repository just now the branch is even with ArduPilot/MAVProxy/master but over time that will change. Enter at the prompt:

cd MAVProxy-ssh/MAVProxy
git remote -v

What this does is call git remote command with the --verbose option. It yields:

origin git@github.com:ArduPilot/MAVProxy.git (fetch)
origin git@github.com:ArduPilot/MAVProxy.git (push)

and this means have access to the origin remote repository with the URL git@github.com:ArduPilot/MAVProxy.git. Now enter:

git remote add my_fork git@github.com:<fork_name>/MAVProxy.git

substituting <fork_name> with the name of your fork. Now enter:

git remote -v

at the prompt and you should get:

my_fork git@github.com:mday299/MAVProxy.git (fetch)
my_fork git@github.com:mday299/MAVProxy.git (push)
origin git@github.com:ArduPilot/MAVProxy.git (fetch)
origin git@github.com:ArduPilot/MAVProxy.git (push)

Now enter (this uses the git fetch command):

git fetch my_fork

Which yields something like:

From github.com:mday299/MAVProxy
* [new branch] OBC-2018 -> my_fork/OBC-2018
* [new branch] WinPathing -> my_fork/WinPathing
* [new branch] gh-pages -> my_fork/gh-pages
* [new branch] master -> my_fork/master
* [new branch] module-wip -> my_fork/module-wip
* [new branch] revert-184-sphinx_docs -> my_fork/revert-184-sphinx_docs
* [new branch] stephen-wip -> my_fork/stephen-wip
* [new branch] stephendade-patch-1 -> my_fork/stephendade-patch-1
* [new branch] stephendade-patch-2 -> my_fork/stephendade-patch-2
* [new branch] stephendade-patch-3 -> my_fork/stephendade-patch-3
* [new branch] tcr-wxcolors -> my_fork/tcr-wxcolors
* [new branch] terrain-wip -> my_fork/terrain-wip

We are ready to start contributing!

Your First Branch

Enter the following:

git branch my-awesome-feature
git checkout my-awesome-feature
git status

Which yields:

On branch my-awesome-feature
nothing to commit, working tree clean

We’ve just done quite a bit there so let’s take time to appreciate what we’ve done:

created a branch
checked out that branch
pulled up a status

Now let’s modify MAVProxy so we have something to commit. Say the README.md file — open it in your favorite editor and add a line the top, e.g., “This is the top line.”

Save the file and again check the status:

git status
On branch my-awesome-feature
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: README.md

no changes added to commit (use "git add" and/or "git commit -a")

Stage the README.md file with git add:

git add README.md
git status
On branch my-awesome-feature
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

modified: README.md

Then commit:

git commit -m "Modified README.md"
[my-awesome-feature 3787e26] Modified README.md
1 file changed, 2 insertions(+)

We are ready to put in our first pull request!

Submitting A Pull Request

A pull request is how we let developers on GitHub know we are ready to discuss something we would like added to their repository. In this case, we use git push and then open a browser to submit a pull request on GitHub:

git push my_fork
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 322 bytes | 322.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'my-awesome-feature' on GitHub by visiting:
remote: https://github.com/mday299/MAVProxy/pull/new/my-awesome-feature
remote:
To github.com:mday299/MAVProxy.git
* [new branch] my-awesome-feature -> my-awesome-feature

The my-awesome-feature is ready for a pull request

Click the “compare and pull request” button and your browser will open:

Be sure to leave as descriptive a comment as possible. If your pull request is approved then congratulations! You’ve made a contribution to open source software!

Next time we’ll explore how to correct mistakes in Git.

Git 3: Collaboration on GitHub