Setup

git clone ssh://USERNAME@code.wireshark.org:29418/wireshark

Git Pre-Commit Hook

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). 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 just remove the .sample suffice from the existing pre-commit.sample file.

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:

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:

Tag

Meaning

Change-Id

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.

Bug

Make Gerrit automatically add a comment and close the given bug number when the commit is merged.

Ping-Bug

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 wireshark.org. (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:

  A
  |
  B
  |
  C
 / \
D   E
|   |
F   |
|   |
G   H
 \ /
  I

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.

Before:

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

After a new commit:

A
|
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: https://code.wireshark.org/review/#/settings/projects 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

Development/SubmittingPatches (last edited 2017-03-17 14:51:31 by RemyLeone)