Getting started with git for OfficeDev/PnP - The more hardcore way

The OfficeDev patterns and practices project is a really great timesaver for any organization doing Office 365 development.

It contains loads of code samples, solutions, components and a really terrific core project (extensions for the csom APIs). The core project is what you will include through NuGet to stop writing a lot of boilerplate code.

But many SharePoint/MS stack devs are still not all that familiar with Git and GitHub, so I thought that in addition to the alreay existing articles it might be worth exploring how to do it in a puristic way.

If all you care about is getting up and running with the least possible resistance then you should head over to the PnP wiki and read the Setting up your environment article. It will tell you step by step how you fork a repo, add it to visual studio and get to work. If you feel that you want to know how to do things without visual studio after having gone through that process, then keep reading.

I personally always prefer to not use the VS abstraction that hides so many of the great features of git. I want to see a glorious monospaced terminal, like this:

Now, let's see how you can reach this nirvana of geekdom.

Step 1 - Get cmder

Cmder is a software package created out of pure frustration over absence of usable console emulator on Windows. It is based on ConEmu with major config overhaul. Monokai color scheme, amazing clink and custom prompt layout.

I really miss having a good console emulator on windows. Cmder is great because it comes bundled with a pre-configured version of [ConEmu] and [msysgit].

So head over to the cmder download page and get a copy.

.

Unzip this to a location of your choosing and optionally add the location to your PATH variable so it's easy to start.

Step 2 - Configure authentication between local git and github

You don't want to keep entering the same credentials every time you do a commit to your origin repo do you? I personally feel that being able to commit early and often is more important than making sure that noone can commit from my workstation. (Note: Please re-evaluate this if you use github for your enterprise, people tend to disagree).

The way we achieve this is by generating a ssh key pair.

It's simple enough, just ssh-keygen and press enter on all the questions.

This will generate two files: id_rsa and id_rsa.pub. We are interested in the .pub file, so pull that over to your clipboard by typing cat ~/.ssh/id_rsa.pub | clip

Now we need to head over to the github ssh-key settings page to add our newly created key.

Keygen generation

Here we give our new key a name and paste it into the textbox.

add key

Now let's test the connection by issuing the ssh -T git@github.com command.

Cmder

Success! Github now knows who we are.

Now let's install another useful tool: git-credential-winstore. This nifty tool saves your credentials when pushing. This also works with non github hosted repositories, like Visual Studio Online.

git-credential-winstore

If you see a login window pop up when you push later you know it's working. Otherwise it will just prompt you for credentials every time you push.

Tip: If you get an error message when installing the git-credentials-winstore telling you that it can't find git.exe you can find that file in the "\vendor\msysgit\bin" catalog in the cmder folder. You can point to that file by running git-credential-winstore.exe -i "path to git.exe"

Step 3 - Get your repos together

This step is optional if you set everything up using the PnP wiki guide, but let's walk through how you do it from the command line instead of the UI. Also note that there is an alternate way to do these things in that wiki, the info below accomplishes the same results but in a way that might make a lightbulb go off in your head.

First we need to clone the forked repo git clone https://github.com/YOURUSERNAME/PnP. Now is a good time to go get more coffee/tea as it's a large repo and it will take a while.

git clone

Next we need some way to keep our fork, our local copy and the original repo in sync. To do this we first add the upstream remote (the pointer to the original OfficeDev repo that we don't have commit access to) with:
git remote add upstream https://github.com/OfficeDev/PnP

Tip: Remember to actually cd PnP before trying to issue git commands aimed at a repository.

Now we can look into what branches we have with git remote -v
git remote -v

As you can see we have origin (our fork on github) and upstream (office dev on github) set up as remotes.

Git what about branches? A git branch -vv just shows us
git branch -vv

Thats not right. We know for a fact that there are other branches on the remotes...

other branches

We can find out what our local repo know about the remote with git branch -r

git branch -r

Ok, it seems that there are a few branches in our fork already from previous work done. Hmm. Let's check one out and see what happens.

detached HEAD

Wait. What. Ok, don't panic. The help message actually tells us exactly what to do. We just checked out a specific commit without telling our local copy of git what to do with it. What we want is to create a new local branch that knows about the relationship with the origin/dev branch. This is easily done either by

a) Doing git branch dev, git checkout dev, git branch --set-upstream-to origin/dev
b) Doing git checkout -b dev origin/dev

newbranch

And now we can see it with git remote -vv

newbranch

But.. Hmm, it seems that our local copy does not know anything about our added upstream branch unless we tell it to. This makes sense, so let's correct this by doing a git fetch upstream

fetch upstream

Ah, great. Now we can start to get our copies in sync.

Let's start by pulling in the changes to our local dev branch from the remote with git checkout dev and git pull upstream dev.

Now that we have a locally merged copy of the upstream and origin dev branches we can push to our forks (origin) dev branch with git push origin dev.

Whew! Finally done. Now we can start to do some work.

Step 4 - Get to work

With our origin, upstream and local repo in sync we can start working on a new pull request.
The process for this is really easy now that we know what goes on with git.

  1. Sync - git checkout dev, git pull upstream dev, git push origin dev
  2. Make sure we base pull request from synced dev with git checkout dev
  3. Create a new local feature branch with git checkout -b new-feature-i-want-the-office-dev-team-to-pull
  4. Do some work
  5. Commit the work
  6. Push the local branch to our fork on github git push origin new-feature-i-want-the-office-dev-team-to-pull
  7. Go to the OfficeDev PnP repo on github
  8. Create your pull request
  9. Wait for someone to merge the pr
  10. Sync - git checkout dev, git pull upstream dev, git push origin dev
  11. Remove your local branch with git branch -d new-feature-i-want-the-office-dev-team-to-pull
  12. Delete your remote branch with git push origin :new-feature-i-want-the-office-dev-team-to-pull (Totally obvious right?)
  13. Repeat for infinite glory.

And there you have it. Simple right? If not, I wrote a part 2 that goes through Step 4 in more detail. You can read it here.

Did you like the post or have something to add? Let me know in the comments!