Project

General

Profile

Git work flow

Note the workflow specific to Github is documented here Github work flow.

Getting the source

First thing to do is to clone the Suricata repository.

git clone git://phalanx.openinfosecfoundation.org/oisf.git

Then you can change directory to the newly created 'oisf' one.

If you are new to git, you will need some tuning:

git config --global user.name "Your Name" 
git config --global user.email "your@mail.com" 

This is necessary to have this information given as it will be used
to fill your personal information when doing and sending patches.

If you want these settings to be specific to Suricata, just removed the '--global' flag.

One last thing of interest is to have git display the branch you are working on. This can
be done by using __git_ps1 function. For example, your PS1 could looks like:

PS1='\u@\h:\w$(__git_ps1 " (%s)") \$ '

Create your branch

git checkout -t -b MyBrightFix origin/master

Now you can work on it. Do your modification to the source, commit it when ready and if your previous
commit was not ok, you can do 'git commit --amend' to modify it. For example, to add all the current
modification to the last commit, you can just do 'git commit -a --amend'.

Don't hesitate to do incremental commit, you will be able to modify your tree later by
running git rebase -i origin/master.

Code formatting

Follow this document: Coding Style

This consideration may appear trivial to some but please take into account that homogeneity
of code presentation is one of the key of good and fast code review.

Reviewing your own work

Before sending your work, this is careful to check it. You can do so by running:

git log -p

It will display all the patches of the current branch including the commit message.
Don't forget the commit message, will be later used and put directly into Suricata's
git source tree if it is accepted. Thus, please take care of formatting and typographic
error.

A good git commit message is structured as:

Subject in 50 characters

All the information needed to understand what the patch is doing and
which choices have been made.

When looking at 'git log -p' output, please check to spacing issue which appear in red in the
output and fix them.

Run a check of your code before sending your patch. You can smply run the make check command
from the source. It is recommended to install coccinelle which will provide some capabilities
for some semantic tests on the code.

Sending your work

First thing to do is to check that your work is syncrhonized with latest modification of git version of Suricata.

To do so, you can run

git pull --rebase

It will update your local git tree to the current version of Suricata and apply your current patches on top of it.
If all goes well, you will have a synchronized tree.

You will now be able to send your patches, first thing is to format them:

git format -o /tmp/MyBrightFix/ origin/master..HEAD

It will generate a file for each patch you've made and pu them in MyBrightFix directory.

Now you can use the git send-email command (available in a separate package called git-email on some distribution).

If you have a single patch and that all explanations are included in the commit message, you can run:

git send-email --to oisf-devel@openinfosecfoundation.org /tmp/MyBrightFix/

If this is not the case, run

git send-email --compose --to oisf-devel@openinfosecfoundation.org /tmp/MyBrightFix/

Fixing problem

Fixing a rebase failure

When doing git pull --rebase, the application of your patches can fail due to some modifications on the source tree. In this case, fix the rebase by following the instruction.

eric@tiger:~/git/oisf (test) $ git pull --rebase
remote: Counting objects: 53, done.
remote: Compressing objects: 100% (49/49), done.
remote: Total 49 (delta 36), reused 0 (delta 0)
Unpacking objects: 100% (49/49), done.
From git://phalanx.openinfosecfoundation.org/oisf
   9b75de3..99baf18  master     -> origin/master
First, rewinding head to replay your work on top of it...
Applying: runmode-pfring: add comment
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
Auto-merging src/runmode-pfring.c
CONFLICT (content): Merge conflict in src/runmode-pfring.c
Failed to merge in the changes.
Patch failed at 0001 runmode-pfring: add comment

When you have resolved this problem run "git rebase --continue".
If you would prefer to skip this patch, instead run "git rebase --skip".
To check out the original branch and stop rebasing run "git rebase --abort".

Basically, the files were a conflict have been found contains the conflicting modifications.
You can have an idea of the conflict by running:
eric@tiger:~/git/oisf ((99baf18...)|REBASE) $ git diff
diff --cc src/runmode-pfring.c
index eec9e94,a1b0f31..0000000
--- a/src/runmode-pfring.c
+++ b/src/runmode-pfring.c
@@@ -82,7 -82,7 +82,11 @@@ void PfringDerefConfig(void *conf
  {
      PfringIfaceConfig *pfp = (PfringIfaceConfig *)conf;
      if (SC_ATOMIC_SUB(pfp->ref, 1) == 0) {
++<<<<<<< HEAD
 +#ifdef HAVE_PFRING_SET_BPF_FILTER
++=======
+       /* Free buffer if allocated */
++>>>>>>> runmode-pfring: add comment
          if (pfp->bpf_filter) {
              SCFree(pfp->bpf_filter);
          }

To fix the code, you need to open the files and make manual modifications. For example, here the file was:

void PfringDerefConfig(void *conf)
{
    PfringIfaceConfig *pfp = (PfringIfaceConfig *)conf;
    if (SC_ATOMIC_SUB(pfp->ref, 1) == 0) {
<<<<<<< HEAD
#ifdef HAVE_PFRING_SET_BPF_FILTER
=======
        /* Free buffer if allocated */
>>>>>>> runmode-pfring: add comment
        if (pfp->bpf_filter) {
            SCFree(pfp->bpf_filter);
        }
#endif
        SCFree(pfp);
    }
}

and becomes:
void PfringDerefConfig(void *conf)
{
    PfringIfaceConfig *pfp = (PfringIfaceConfig *)conf;
    if (SC_ATOMIC_SUB(pfp->ref, 1) == 0) {
#ifdef HAVE_PFRING_SET_BPF_FILTER
        /* Free buffer if allocated */
        if (pfp->bpf_filter) {
            SCFree(pfp->bpf_filter);
        }
#endif
        SCFree(pfp);
    }


Once the file is saved, run git add $FILE. Once all files are fixed, run git rebase --continue.
eric@tiger:~/git/oisf ((99baf18...)|REBASE) $ git add src/runmode-pfring.c
eric@tiger:~/git/oisf ((99baf18...)|REBASE) $ git rebase --continue
Applying: runmode-pfring: add comment