You may have seen xkcd’s comic about git:

I feel this pain. Because of Mailman, I actually learned Bazaar when many people were learning git, and did most of my contributions through launchpad, so I’m a relative newcomer to git and doing contributions on github (Mailman’s on gitlab now, but I do github for work and other reasons). This is constantly embarrassing to me because I’m a pretty seasoned open source contributor and so people always assume that I’ll be good at git. But I’m not. And lots of other people aren’t either! I was amused at how quickly that comic made the rounds with everyone saying things like, “I thought it was just me!”

Of course, my boyfriend not only does git but used to develop gitweb, so he was horrified when I laughed at said comic and thus cemented his role as my personal git tech support forever. I am both relieved and horrified that he has to look this stuff up all the time too.

Anyhow, in the interest of making my own life easier, I’m writing myself a teensy tiny reminder of the parts of git I most often get wrong. (It’s possible that this tutorial is also wrong, but I’m bugging J as I go so I don’t screw it up too badly.) I’m hoping that writing it out will make it easier to remember, but if not, at least I know where to look.

Setting up my repo

1. Fork
   I do this through the web interface so I have a personal copy to work with and sometimes so I don’t accidentally try to push directly upstream on projects like Mailman where I totally could do that if I wasn’t paying attention.

2. Clone my fork on my local machine
   This makes a nice local copy I can poke at and grep through and whatever.
   git clone git@gitlab.com:terriko/mailman-website.git

3. Set up an upstream
   This helps make it easier for me to get changes from the upstream original project and integrate them into my local copy.

   cd mailman-website
git remote add upstream git@gitlab.com:mailman/mailman-website.git

4. If I want to get changes from upstream, I then do
   git fetch upstream
git merge upstream/master
   
   *** see note below

Note to self: don’t use git pull. I know that git pull basically just fetches and merges, but somehow I always screw something up with it if I have changed any file anywhere. As far as I know, git pull seems to be the equivalent of releasing angry flaming wasps into your repository. You might try to clean it up for a while, but eventually you’re going to decide that dealing with flaming wasps is way more hassle than just making a new repo copy and going there.

I know, the guides always tell you to use git pull. I assume most of the guides on the internet are written by angry flaming wasps who desire new homes in your repo.

*** Edited to add: my friend e suggests that merge here might be another source of fire wasps depending on what you want to do. git rebase may be the better choice.

Making a branch

Note to self: always make the branch before making any changes or you’ll find a way to get your tree into some sort of screwed up state and all the git stash and revert attempts in the world won’t push your mess out of the way enough to make git happy. The flaming wasps will win again.

git checkout -b mailman3doc --track
(This will use my upstream settings (set above) and tie this branch to that upstream. With magic.)

Saving my work and pushing it publicly

When I want to check stuff into my branch (aka save what I’m working on) I do

1. Add the ones I want to save
   
git add $files_I_have_changed_and_want_to_save


   If I’m not sure which files I changed, I can check

   git status

   Note to self: I never forget how to add, but I often try to use git diff instead of git status so that’s why this is here.

2. Check in my files
   git commit -m "Useful commit message goes here"

   I also rarely forgot this one, because it’s basically unchanged from the first version control systems I used. yeay!

3. The first time I want to push my branch to gitlab or github, I do
   git push -u origin $branchname

   The -u part sets the magic for the branch so that in theory in the future I can just use

   git push

Note to self: The -u stands for “upstream” but after some point, I’m losing track of what is upstream and what is origin and I can never remember what I need here. It’s all magic incantations as far as my memory goes.

Cleaning up my commit messages before a merge

Often I make a commit, push it upstream, then realize that I have a typo in a comment or something that I want to fix quietly without anyone knowing. Thankfully, git rebase is here for me. If it’s just gone to my personal fork and not to the main repo, I can use it to hide my shame.

git rebase -i HEAD~2

Will “interactively” let me mess with my last two commits. There’s a nice tutorial on how to do this here so I won’t write one out myself.

That’s the most common ones I can think of off the top of my head!