Privoxy Developer Manual
Prev |  | Next

# 2. The Git Repository

If you become part of the active development team, you will eventually need write access to our holy grail, the Git repository. One of the team members will need to set this up for you. Please read this chapter completely before accessing via Git.

## 2.1. Access to Git

The project's Git repository is hosted on the Privoxy webserver. For Privoxy team members with push privileges the Git repository URL is `ssh://git@git.privoxy.org:23/git/privoxy.git`.

Contributors without push privileges can "git clone https://www.privoxy.org/git/privoxy.git".

The central repository is called `privoxy`, and the source branch is called `master`. Subfolders exist within the project for target-dependent build and packaging tools, each including the name of the target operating system in their name (e.g. Windows, OSXPackageBuilder, debian). There is a webview of the Git hierarchy at https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree, which might help with visualizing how these pieces fit together.

## 2.2. Branches

Whilst the central repository contains only the master branch, developers are of course free to create branches in their local repositories as they develop features, fixes, or update the target-dependent tools. Only once such changes are fully tested ought they be pushed back to the central repository master branch.

Before pushing stuff, please rebase it on a current master so we get an uncomplicated commit history. Avoid merges where possible.

Here's an example git sesssion that should result in a merge-free history:

    fk@t520 ~/git/privoxy $git checkout master
    Switched to branch 'master'
    Your branch is up to date with 'origin/master'.
    # Make sure you have the latest changes
    fk@t520 ~/git/privoxy $git pull
    Already up to date.
    # Create a local banch for changes
    fk@t520 ~/git/privoxy $git checkout -b local-branch
    Switched to a new branch 'local-branch'
    # Create some change
    fk@t520 ~/git/privoxy $gmake dok dok-tidy
    [...]
    # Review your change
    fk@t520 ~/git/privoxy $git diff
    [...]
    # Commit your changes if they look goood
    fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/
    [local-branch 1abb7316] developer-manual: Regenerate
     1 file changed, 2 insertions(+), 2 deletions(-)
    # Review your commit
    fk@t520 ~/git/privoxy $git show
    [...]
    # Go to the master branch
    fk@t520 ~/git/privoxy $git checkout master
    Switched to branch 'master'
    Your branch is up to date with 'origin/master'.
    # Make sure you are still in sync
    fk@t520 ~/git/privoxy $git pull
    [...]
    Already up to date.
    # Apply the commit you made to the local-branch
    fk@t520 ~/git/privoxy $git cherry-pick local-branch
    [master 046e85e2] developer-manual: Regenerate
     Date: Tue Dec 15 05:10:07 2020 +0100
     1 file changed, 2 insertions(+), 2 deletions(-)
    # Make sure the history looks as expected
    fk@t520 ~/git/privoxy $git log -p
    # Finally push your change to the Privoxy repository
    fk@t520 ~/git/privoxy $git push
    [...]
    # Go back to the local branch
    fk@t520 ~/git/privoxy $git checkout local-branch
    # Rebase on top of master and continue hacking
    fk@t520 ~/git/privoxy $git rebase master
    Successfully rebased and updated refs/heads/local-branch.

At one time there were two distinct branches: stable and unstable. The more drastic changes were to be in the unstable branch. These branches have now been merged to minimize time and effort of maintaining two branches.

## 2.3. Git Commit Guidelines

The source tree is the heart of every software project. Every effort must be made to ensure that it is readable, compilable and consistent at all times. We expect anyone with Git access to strictly adhere to the following guidelines:

Basic Guidelines, for all branches:

- Please don't commit even a small change without testing it thoroughly first. When we're close to a public release, ask a fellow developer to review your changes.

- Your commit message should give a concise overview of what you changed (no big details) and why you changed it Just check previous messages for good examples.

- Don't use the same message on multiple files, unless it equally applies to all those files.

- If your changes span multiple files, and the code won't recompile unless all changes are committed (e.g. when changing the signature of a function), then commit all files one after another, without long delays in between. If necessary, prepare the commit messages in advance.

- Before changing things on Git, make sure that your changes are in line with the team's general consensus on what should be done.

- Note that near a major public release, we get more cautious. There is always the possibility to submit a patch to the patch tracker or the privoxy-devel mailing list instead.

Prev | Home | Next
Introduction |  | Documentation Guidelines