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