Git workflows, good practices
An opinionated guide

Table of Contents

Salut à toi ! Bienvenue dans la bidouille !

Utilise « C-c C-o » (control+c puis control+o) pour suivre les liens (les trucs soulignés en bleu ci-dessous).

Ce fichier est disponible à http://sed.bordeaux.inria.fr/la-bidouille ou http://people.bordeaux.inria.fr/lcourtes/git-workflox.org.

1 code is a social process

1.1 it’s all about cooperating with others

2 optimize for review, bisect, and analysis

2.1 why should i care?

2.1.1 make it easier for coworkers to understand what you’re doing

2.1.2 facilitate bug hunting with ‘git bisect’

2.1.3 make it easier to understand changes in the future (‘git annotate’)

2.2 “atomic” commits: one set of related changes at a time

2.2.1 when fixing a bug: include fix and test in the commit

2.2.2 when adding a feature: include feature + tests + doc

2.3 picking changes for a commit

2.3.1 never use “git commit -a”: you may end up committing stuff unwillingly!

git commit -a is roughly equivalent to git add * && git commit.

2.3.2 Git’s staging area (aka. “the index”)

  • git add foo adds ‘foo’ to the index (IOW, it stages changes to ‘foo’)
  • git commit commits what’s in the index (IOW, it commits changes that were previously staged)

2.3.3 select the right “hunks” for your commit

  • git add -p to interactively select hunks
  • S in Magit to stage a given hunk

2.3.4 stash unrelated changes away

git stash                       # "stashes away" working-tree changes
# hack on stuff...
git commit                      # commit the things
git stash pop                   # reinstate stashed changes

2.3.5 tools

  1. Magit (Emacs)

    magit.png

  2. Fugitive (Vim)
  3. at the command line: pretty hard inconvenient

2.4 comments usually belong in the code, not in the commit log

2.5 keep related changes in a branch (possibly a series of several commits)

2.5.1 example: feature branch, doc branch

3 submitting code

3.1 submit the whole set of related changes at once

Could be one commit (e.g., bug fix), or could be a whole series (e.g., add feature X).

3.2 check the submission checklist (if there’s one)

3.3 rebase your submission branch on the target branch

This will simplify the reviewers life by make sure the changes apply on the latest ‘master’, for example. 

git checkout master
git pull           # update my copy of 'master'
git checkout my-feature-branch
git rebase master  # rebase 'my-feature-branch' on 'master'

See this for a discussion of rebasing.

3.4 by email

3.4.1 step 0: set your name and email address

git config --global user.email
git config --global user.name

3.4.2 step 1: ‘git format-patch’

git checkout wip-cool-feature
git format-patch master

or: 

git format-patch --cover-letter

3.4.3 step 2: ‘git send-email’

git send-email 0*.patch

3.5 by pushing code somewhere

git push wip-foo my-remote-server

3.6 on GitLab

3.6.1 create a “fork”

example: Chameleon forks

3.6.2 create a topic-specific branch

example: ‘fpruvost:updatetexinfo’ branch

3.6.3 create a merge request

example: Chameleon merge request

4 reviewing code

4.1 stay focused: comment on the actual changes

4.1.1 resist the temptation to discuss wider changes

4.1.2 don’t require submitters to fix things that were already broken

4.2 rely on automation for the boring part of the review

4.2.1 code style checkers, etc.

4.3 iterating

4.3.1 the process: (1) submit, (2) review, (3) goto 1

4.3.2 iteration history

  1. squash intermediate commits because they don’t matter
  2. adjust commits and commit logs according to review
    git add foo                     # stage changes
git commit --amend              # amend the last commit on the branch
  3. how to squash/rewrite commits?
    1. command line: ‘git rebase -i’
    2. Magit

4.4 reviewing tools

4.4.1 email! :-)

examples:

4.4.2 GitLab

4.4.3 Gerrit

4.4.5 Trac

4.4.6 discussion of email vs. web tools

5 keeping the history linear

5.1 what ‘git merge’ and ‘git pull’ (and ‘git push’ sometimes) do

5.1.1 creates a “merge commit”

see the awesome Git for Computer Scientists

5.1.2 show example of linear and non-linear history

5.2 why should i care?

5.2.1 helps understand code evolution

5.2.2 helps bisection (‘git bisect’)

5.2.3 possibly helps continuous integration

5.3 visualizing the history

  • using gitk (which is part of Git)
  • using Magit
  • using a Web interface (GitLab, cgit, etc.)

5.4 pull/merge requests

5.4.1 by default, they introduce merge commits!

5.5 rebasing

5.5.1 the Git commit graph

Do not miss Git for Computer Scientists!

5.5.2 rebasing your changes before pushing

For example, assuming you are working on the ‘master’ branch and have a bunch of local commits ready to be pushed, you would run these commands: 

$ git pull --rebase  # fetch remote changes, and rebase on top of them
$ git push

Sometimes ‘git pull –rebase’ will result in conflicts that need to be resolved. Assuming ‘foo.cpp’ has a conflict, you would edit it to fix those conflicts (look for “>>>”), and then: 

$ git add foo.cpp
$ git rebase --continue

5.5.3 rebasing a branch on master

Before submitting, rebase your branch on top of ‘master’. See details here.

Created: 2019-11-15 or. 18:54

Validate