git config

Guideline for (new) contributors

This page outlines a good guideline for new contributors who are not used to git and Github. A few things are to do to start contributing code to the project. This doesn't claim to be a git man page, but just an easy guide to start coding for ettercap in 10 minutes. If you are new to Github at all, lets start with some explanation beforehand.

The philosophy behind Github is slightly different to the traditional BugZilla and Mailinglist approach. Patches are not submitted using Bugzilla, they are submitted by creating a pull-request (pull code from other forks back into the original master). Each pull-request is a set of commits which changes are discussed over the Github web front-end before they gonna be merged. However, email can also be used to get updates of the discussions and even to answer.

Before we proceed I want to mention that there is even a way to create a pull-request without getting bothered by anything around git and what's described below. For small changes you can also just edit the file using the Github inline editor and save your changes. This automatically creates a pull-request without forking the repository or knowing git!

But if you plan to hand in more complex changes, we still recommend to read further and discover the power of git.

A useful set of Github tricks!

First of all, be adviced about this impressive collection of tips and tricks to use Github in a more efficient way. If you want to use graphic clients you can install gitg (Gnome/GTK) or gitk (KDE/QT). However this guide focuses on the CLI command git.

Basic steps before start helping:

• setup a github account
• fork ettercap project
• clone your fork locally ($ git clone https://github.com/<youraccountname>/ettercap)

Now you have the source code of ettercap available on your computer. But before you do your changes, please proceed reading that helps in maintaining your repository.

Guidelines how to contribute to the project

Link your local copy with the ettercap master repository

The next step is to link the ettercap master repository as the upstream of your local copy:

$ git remote add upstream https://github.com/Ettercap/ettercap.git

this way you get the latest updates on the upstream repository by calling

$ git fetch upstream

To automatically fetch the latest pull-requests you have to edit your .git/config (relative to your local copy) and add in the upstream section the following line

fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

Next time you fetch the upstream using the above fetch-command you will also fetch the pull requests which are treated as remote branches. To test a particular pull-request, create and change into a new branch from your master branch and merge the changes of the pull-request by using the command:

$ git merge upstream/pr/Number

Always work with branches

Keep your master branch clean! Use it just as a copy of the latest master branch of ettercap. You can keep it up 2 date using:

$ git fetch upstream 
$ git checkout master
$ git merge upstream/master

When you work on a particular fix/issue/feature, it is good practice and stronly recommended to create a dedicated branch for it, this will help a lot in reviewing the code. DON'T fix two or more issues in a single branch! Better do three different branches and pull requests instead, unless commits are strictly correlated.

$ git checkout master
$ git checkout -b fix-Number

Now you can do your changes. All these changes are related to this branch (check $ git branch to find out on which branch you're currently working on). After you finished your work, sync your local branch to your remote repository on Github:

$ git push origin fix-Number

Note that fix-Number is just an example for a branch name and can be replaced by anything else.

if you want to create a new branch for fixing another issue it is always better switch back to your master branch and to start from there

Keep in sync with changes on the upstream repository

Sometimes it happens, that your or someone elses changes have been merged into the ettercap master. In such cases conflicts might occur that prevents your branch (pull-request) to be merged into the ettercap master. To resolv this you should rebase your changes onto the latest changes of upstream. First fetch the latest upstream changes then just rebase your commits (rewind your changes, merging upstream/master and commit again).

$ git fetch upstream
$ git rebase upstream/master

In some cases you are prompted to resolve conflicts by hand.

$ vi <conflictingfile>
$ git add <conflictingfile>
$ git rebase --continue

NOTE: When you rebase, your commit hashes change. You will fail to push again to your repository. You have to force the push (overwrite).

$ git push -f origin <yourbranch>

if you want to delete some commits you can use

git log (copy the last commit id you want to keep)

git reset --hard commit-id

this will ERASE your history, use it with caution (you still can recover your history even after a reset "hard", but this isn't the topic of this guide, git reflog helps you anyway)

git push -f for overriding the remote history

if you want to fetch the latest master code

git checkout master

git fetch upstream

git merge upstream/master

git push

leaving master "clean" will avoid merge issues when fetching new commits

if you want to commit only some files

git commit filename1 filename2

if you want to export your commit as patch

git format-patch -n (last n commit)

this will create n patch files that can be imported easily with

git am filename

keeping the author, message, id and every git reference

if you want to see files changed on a particular commit

git whatchanged

if you want to merge "meld" two commits together

git rebase -i HEAD~2 or the number of commits you want to meld

after you edit the word "pick" to "f" for fixup (it will be melded with the upper one, the first commit cannot be "f") or other words.

After this you have less commits, but you rewrote the history so you have to "push -f" to force a rewrite on your repository

After your pull request has been accepted and merged you can safely remove your branch with

git branch -D branch-name

git push origin --delete branch-name