This wiki has been migrated to and is now deprecated. Please use that site instead.


git clone ssh://

Git Hooks

In your local repository directory, there will be a .git/hooks/ directory, with sample git hooks for running automatic actions before and after git commands. The git review -s at the end of the previous section installed a commit-msg hook here. If you don't use git review you have to install the commit-msg hook from the tools directory yourself, in order to generate the Change-ID required by Gerrit. Copy the commit-msg file from the tools directory (cp ./tools/commit-msg .git/hooks/) and make sure it is executable or it will not be run. You can also optionally install other hooks that you find useful.

In particular, the pre-commit hook will run every time you commit a change and can be used to automatically check for various errors in your code. The sample git pre-commit hook simply detects whitespace errors such as mixed tabs and spaces; to install it, rename the existing .git/hooks/pre-commit.sample file to .git/hooks/pre-commit.

Wireshark provides a custom pre-commit hook which does additional Wireshark-specific API and formatting checks, but it might return false positives. If you want to install it, copy the pre-commit file from the tools directory (cp ./tools/pre-commit .git/hooks/) and make sure it is executable or it will not be run.

If the pre-commit hook is preventing you from committing what you believe is a valid change, you can run git commit --no-verify to skip running the hooks. Warning: using --no-verify avoids the commit-msg hook, and thus will not automatically add the required Change-ID to your commit. In case you are not updating an existing patch you may generate a Change-ID by running git review -i (or git commit --amend if don't use git review).

Submitting a Change

The review process

To see the status of the review process, go to the URL returned in the previous step and see/discuss the patch and its current review status.

Alternatively the gerrit command line may be used:

Useful gerrit commands:

Find them all here.

Writing a Good Commit Message

When running git commit, you will be prompted to describe the change. Here are some guidelines on how to make that message actually useful to other people (and to scripts that may try to parse it):

You can also add metadata at the bottom of the commit message which will be used by Gerrit for searching and triggering Bugzilla integration. Each line of the footer is of the form Label: value. There can be no extra line-breaks between footer lines.

Wireshark currently supports the following metadata tags:




A unique hash describing the change, which is generated automatically by the git commit-msg hook which you installed during setup. This should not be changed, even when rebasing or amending a commit following code review. If you pass --no-verify to git commit you will have to add this line yourself.


Make Gerrit automatically add a comment and close the given bug number when the commit is merged. For use when the change does fully fix the issue.


Make Gerrit just add a comment to the referenced bug. For use when the change is related but does not fully fix the issue.

(!) The Bug and Ping-Bug tags are particularly useful if a capture file has been provided via a Bugzilla entry in parallel with the change. All non-trivial fixes to dissectors should try to do this.

Putting all that together, we get the following example:

    MIPv6: fix dissection of Service Selection Identifier

    APN field is not encoded as a dotted string so the first character is not a length

    Bug: 10323
    Change-Id: Ia62137c785d505e9d0f1536a333b421a85480741

Amending a Change

If you need to upload a new version of an existing change to the same review.

If you've already accidentally made multiple commits, you can squash them down into one commit by running git rebase -i master, and changing all but the very first pick into squash in the interactive dialogue (see here for more details). Be sure the preserve the Change-ID line of your original commit, not the most recent!

Fixing merge errors

Sometimes a reviewer/core developer will tell you your change has merge issues. This just means some other changes have conflicted with your change in ways that git cannot fix automatically. To resolve this, you need to fix the merge errors in your local branch and push a new patch set to gerrit for the same review. Here are the steps:

CONFLICT (content): Merge conflict in ui/qt/main_window.ui
Auto-merging ui/qt/main_window.h
Failed to merge in the changes.

Deleting your changes

At some point (hopefully soon) your code changes will be merged into the master branch on (well, technically they're cherry-picked and then committed and pushed, but close enough) When that happens, it's safe to delete your local changes branch. You could force git to delete it using the -D option, but this is a better/cleaner way:

Testing a Change from Gerrit

If somebody else has uploaded a change to gerrit you want to test locally (without submitting it to master):

Undoing a Change

If you haven't committed yet and want to undo changes to a file, run git checkout $FILES to revert to the last version. To undo changes to the whole tree, run git checkout with no path.

If you've staged a change with git add but haven't committed yet, run git reset HEAD $FILES to unstage them (and then git checkout to actually undo the changes). Note that "HEAD" is literal text, not a variable.

If you're change is in master, you should revert the change in a new commit with git revert $SHA. This generates a new commit, which must go through the normal Gerrit review process.

A Super-Short Overview of Git

Git manages a collection of commits, each identified by its unique SHA. Each commit (except the very first) contains a pointer to one or more parent commits, thus forming a history (technically a DAG).

Since multiple commits can have the same parent, and a single commit can have multiple parents, this allows branches of development to diverge and be merged. A branch diverges when two commits share a parent, and the branch merges when a single commit contains both branches as its parent:

 / \
D   E
|   |
F   |
|   |
G   H
 \ /

A label is a fixed mapping from a text string to a commit SHA, so for example tag "v1.10.6" simply points to SHA "3dac78778cca8a7838350c67d322c90053977d8a" which is a commit.

A "branch" is exactly the same; a mapping from a text string to a commit SHA. However, a branch is not fixed; when you make a new commit whose parent is currently a branch, that branch is updated to the new commit.


B <- branch: master-1.10, tag: v1.10.6

After a new commit:

B <- tag: v1.10.6
C <- branch: master-1.10

You can run git checkout BRANCHNAME to switch between branches you're working on, branches you're reviewing, and master.

A more comprehensive description of git can be found in this book

Watching changes

If you want to keep track of the changes happening on a specific file, you can using gerrit. Go to your settings page: In the tab Watched projects, add a watch for every file you want to watch by first selecting Wireshark in the project Name and then apply a filter in the Only-if look alike: file:path/towards/my/file

Sample workflow commands

The sample below demonstrates the workflow for a patch. Replace mybranchname with the name you choose for your branch:

$ # Prepare to submit a patch
$ git clone ssh://
$ cd wireshark
$ git review -s
$ git checkout -b mybranchname
Switched to a new branch 'mybranchname'

$ # Make some changes
$ git commit
$ git review
remote: Resolving deltas: 100% (2/2)
remote: Processing changes: new: 1, refs: 1, done    
remote: New Changes:
To ssh://

$ # Optional: Give your code a +1 and add a message
$ ssh -p 29418 gerrit review 398,1 --submit --code-review +1 --message "'Please review and run Petri Dish'"

$ # Add changes for a second patchset (e.g.: Added additional tests)
$ git commit -a --amend
$ git review -R
$ # Optional: Add a message:
$ ssh -p29418 gerrit review 398,1 --message "'Added unit tests'"

$ # Work complete! Delete the mybranchname branch
$ git checkout master
Switched to branch 'master'
$ git branch -D mybranchname
Deleted branch mybranchname (was c159b39).

$ # Oops! Need to make more changes to the mybranchname branch
$ git review -d 398

Development/SubmittingPatches (last edited 2020-05-22 17:38:31 by ChuckCraft)