*.egg

*.mo

.eggs/

tarballcache/

syntax: regexp

^rcextensions

^build

^dist/

^docs/build/

^docs/_build/

^data$

^kallithea/tests/data$

^sql_dumps/

^\.settings$

^\.project$

^\.pydevproject$

^\.coverage$

^kallithea\.db$

^test\.db$

^Kallithea\.egg-info$

^my\.ini$

^fabfile.py

^\.idea$

9ab21c5ddb84935bea5c743b4e147ed5a398b30c rhodecode-0.0.1.3.2

934906f028b582a254e0028ba25e5d20dd32b9cd rhodecode-0.0.1.3.3

af21362474e3ab5aa0e2fbb1c872356f2c16c4f3 rhodecode-0.0.1.3.4

0e2792e04bd316fe64335cbe6a476031ac60b29b rhodecode-0.0.1.3.5

edfff9f37916389144d3a3644d0a7d7adfd79b11 rhodecode-0.0.1.3.6

9ae95fdeca184f2404205645f06c6597b74ef2db rhodecode-0.0.1.4.0

909143a4dde53c46d4f24abb426ec870471c7de1 rhodecode-0.0.1.4.1

d998cc84cf726798486a438763053f0e1dc1b646 rhodecode-0.0.1.4.2

3f5d40b9dd99ccb009ea2211ee2d4b594c634946 rhodecode-0.0.1.4.3

3148c08cf86f1849917e2d50f7ab7766c1550b0a rhodecode-0.0.1.4.4

a5f0bc867edc88be23eb808693e5393a97d4c54a rhodecode-0.0.1.5.0

3259dc7caea48687eab018ee646ae6ad7e7ef377 rhodecode-0.0.1.5.1

efe23d6c178c11d575a0214181276a3452776e48 rhodecode-0.0.1.5.2

1a498b11f1540f5b94b6f6009298f5dc3eaad9e9 rhodecode-0.0.1.5.3

3447862ad8c9ceba85857774c526e39fde3a2281 rhodecode-0.0.1.5.4

c15d7b336af58df9f1bbc8f8957464e7ea618d4c rhodecode-0.0.1.6.0rc1

78b53ee0d247f90d51b028307ff5717851b6c265 rhodecode-0.0.1.6.0

351ad34d56321349ff5bd38f537bd768b8efef2e rhodecode-0.0.1.7.0

1f71ef689d2a3c9978cea6591a1f4e9107a5ca83 rhodecode-0.0.1.7.1

cc48c1541c7e2e84114bf92a0f9cd4b8b1341545 0.0

d17e88a1a88a29f6fac948c94498129e405a40d3 0.1

ad0ce803b40cb17fc3988373052943e041030b02 0.2

c6e32714336345403adf76abb6ebf9b8116fcdc7 0.2.1

14f488a5dc4ca6647bc6acf12534fd137e968aa8 0.2.2

    Balázs Úr <urbalazs@gmail.com> 2015

    Ben Finney <ben@benfinney.id.au> 2015

    Branko Majic <branko@majic.rs> 2015

    Daniel Hobley <danielh@unity3d.com> 2015

    David Avigni <david.avigni@ankapi.com> 2015

    Denis Blanchette <dblanchette@coveo.com> 2015

    duanhongyi <duanhongyi@doopai.com> 2015

    EriCSN Chang <ericsning@gmail.com> 2015

    Étienne Gilli <etienne.gilli@gmail.com> 2015

    Grzegorz Krason <grzegorz.krason@gmail.com> 2015

    Jan Heylen <heyleke@gmail.com> 2015

    Kazunari Kobayashi <kobanari@nifty.com> 2015

    Kevin Bullock <kbullock@ringworld.org> 2015

    kobanari <kobanari@nifty.com> 2015

    Marc Abramowitz <marc@marc-abramowitz.com> 2015

    Marc Villetard <marc.villetard@gmail.com> 2015

    Matthias Zilk <matthias.zilk@gmail.com> 2015

    Michael Pohl <michael@mipapo.de> 2015

    Michael V. DePalatis <mike@depalatis.net> 2015

    Morten Skaaning <mortens@unity3d.com> 2015

    Nick High <nick@silverchip.org> 2015

    Niemand Jedermann <predatorix@web.de> 2015

    Peter Vitt <petervitt@web.de> 2015

    Robert Martinez <ntttq@inboxen.org> 2015

    Ronny Pfannschmidt <opensource@ronnypfannschmidt.de> 2015

    Sam Jaques <sam.jaques@me.com> 2015

    Søren Løvborg <sorenl@unity3d.com> 2015

    Tuux <tuxa@galaxie.eu.org> 2015

    Viktar Palstsiuk <vipals@gmail.com> 2015

    Dominik Ruf <dominikruf@gmail.com> 2012 2014

    Bradley M. Kuhn <bkuhn@sfconservancy.org> 2014

    Calinou <calinou@opmbx.org> 2014

    Daniel Anderson <daniel@dattrix.com> 2014

    Henrik Stuart <hg@hstuart.dk> 2014

    Ingo von Borstel <kallithea@planetmaker.de> 2014

    Jelmer Vernooij <jelmer@samba.org> 2014

    Jim Hague <jim.hague@acm.org> 2014

    Matt Fellows <kallithea@matt-fellows.me.uk> 2014

    Max Roman <max@choloclos.se> 2014

    Michal Čihař <michal@cihar.com> 2014

    Na'Tosha Bard <natosha@unity3d.com> 2014

    Rasmus Selsmark <rasmuss@unity3d.com> 2014

    Tim Freund <tim@freunds.net> 2014

    Travis Burtrum <android@moparisthebest.com> 2014

    Zoltan Gyarmati <mr.zoltan.gyarmati@gmail.com> 2014

    Marcin Kuźmiński <marcin@python-works.com> 2010-2013

    xpol <xpolife@gmail.com> 2012-2013

    Aparkar <aparkar@icloud.com> 2013

Kallithea can be run as standalone hosted application on your own server. It is

open-source donationware and focuses more on providing a customised,

self-administered interface for Mercurial_ and Git_ repositories. Kallithea

works on Unix-like systems and Windows, and is powered by the vcs_ library

created by Łukasz Balcerzak and Marcin Kuźmiński to uniformly handle multiple

version control systems.

Kallithea was forked from RhodeCode in July 2014 and has been heavily modified.

Installation

------------

Kallithea requires Python_ 2.x and it is recommended to install it in a

virtualenv_. Official releases of Kallithea can be installed with::

    pip install kallithea

The development repository is kept very stable and used in production by the

developers -- you can do the same.

Please visit https://docs.kallithea-scm.org/en/latest/installation.html for

more details.

Source code

-----------

The latest sources can be obtained from

https://kallithea-scm.org/repos/kallithea.

The issue tracker and a repository mirror can be found at Bitbucket_ on

https://bitbucket.org/conservancy/kallithea.

Kallithea features

------------------

- Has its own middleware to handle Mercurial_ and Git_ protocol requests. Each

  request is authenticated and logged together with IP address.

- Built for speed and performance. You can make multiple pulls/pushes

  simultaneously. Proven to work with thousands of repositories and users.

- Supports http/https, LDAP, AD, proxy-pass authentication.

- Full permissions (private/read/write/admin) together with IP restrictions for

  each repository, additional explicit forking, repositories group and

  repository creation permissions.

- User groups for easier permission management.

- Repository groups let you group repos and manage them easier. They come with

Converting from RhodeCode

-------------------------

Currently, you have two options for working with an existing RhodeCode

database:

- keep the database unconverted (intended for testing and evaluation)

- convert the database in a one-time step

Maintaining interoperability

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Interoperability with RhodeCode 2.2.X installations is provided so you don't

have to immediately commit to switching to Kallithea. This option will most

likely go away once the two projects have diverged significantly.

To run Kallithea on a RhodeCode database, run::

   echo "BRAND = 'rhodecode'" > kallithea/brand.py

This location will depend on where you installed Kallithea. If you installed

via::

then you will find this location at

``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``.

One-time conversion

~~~~~~~~~~~~~~~~~~~

Alternatively, if you would like to convert the database for good, you can use

a helper script provided by Kallithea. This script will operate directly on the

database, using the database string you can find in your ``production.ini`` (or

``development.ini``) file. For example, if using SQLite::

   cd /path/to/kallithea

   cp /path/to/rhodecode/rhodecode.db kallithea.db

   pip install sqlalchemy-migrate

.. Note::

   If you started out using the branding interoperability approach mentioned

   above, watch out for stray brand.pyc after removing brand.py.

Git hooks

~~~~~~~~~

After switching to Kallithea, it will be necessary to update the Git_ hooks in

your repositories. If not, the Git_ hooks from RhodeCode will still be called,

which will cause ``git push`` to fail every time.

If you do not have any custom Git_ hooks deployed, perform the following steps

(this may take some time depending on the number and size of repositories you

have):

1. Log-in as an administrator.

2. Open page *Admin > Settings > Remap and Rescan*.

3. Turn on the option **Install Git Hooks**.

4. Turn on the option **Overwrite existing Git hooks**.

5. Click on the button **Rescan Repositories**.

If you do have custom hooks, you will need to merge those changes manually. In

order to get sample hooks from Kallithea, the easiest way is to create a new Git_

repository, and have a look at the hooks deployed there.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _Python: http://www.python.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _Mercurial: http://mercurial.selenic.com/

.. _Bitbucket: http://bitbucket.org/

.. _GitHub: http://github.com/

.. _Subversion: http://subversion.tigris.org/

.. _Git: http://git-scm.com/

.. _Celery: http://celeryproject.org/

.. _vcs: http://pypi.python.org/pypi/vcs

.. _Software Freedom Conservancy: http://sfconservancy.org/

## Default:

#email_prefix =

## Example:

#email_prefix = [Kallithea]

## Recipients for error emails and fallback recipients of application mails.

## Multiple addresses can be specified, space-separated.

## Only addresses are allowed, do not add any name part.

## Default:

#email_to =

## Examples:

#email_to = admin@example.com

#email_to = admin@example.com another_admin@example.com

## 'From' header for error emails. You can optionally add a name.

## Default:

#error_email_from = pylons@yourapp.com

## Examples:

#error_email_from = Kallithea Errors <kallithea-noreply@example.com>

#error_email_from = paste_error@example.com

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

#smtp_username =

#smtp_password =

#smtp_port = 25

#smtp_use_tls = false

#smtp_use_ssl = false

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.

#smtp_auth =

[server:main]

## PASTE ##

#use = egg:Paste#http

## nr of worker threads to spawn

#threadpool_workers = 5

## max request before thread respawn

#threadpool_max_requests = 10

## option to use threads of process

#use_threadpool = true

## WAITRESS ##

use = egg:waitress#main

## number of worker threads

threads = 5

## MAX BODY SIZE 100GB

## use Strict-Transport-Security headers

use_htsts = false

## number of commits stats will parse on each iteration

commit_parse_limit = 25

## path to git executable

git_path = git

## git rev filter option, --all is the default filter, if you need to

## hide all refs in changelog switch this to --branches --tags

#git_rev_filter = --branches --tags

## RSS feed options

rss_cut_off_limit = 256000

rss_items_per_page = 10

rss_include_diff = false

## options for showing and identifying changesets

show_sha_length = 12

show_revision_number = false

## gist URL alias, used to create nicer urls for gist. This should be an

## url that does rewrites to _admin/gists/<gistid>.

gist_alias_url =

## white list of API enabled controllers. This allows to add list of

## controllers to which access will be enabled by api_key. eg: to enable

## api access to raw_files put `FilesController:raw`, to enable access to patches

## add `ChangesetController:changeset_patch`. This list should be "," separated

## Syntax is <ControllerClass>:<function>. Check debug logs for generated names

## Recommended settings below are commented out:

api_access_controllers_whitelist =

#    ChangesetController:changeset_patch,

#    ChangesetController:changeset_raw,

#    FilesController:raw,

#    FilesController:archivefile

## default encoding used to convert from and to unicode

## can be also a comma seperated list of encoding in case of mixed encodings

default_encoding = utf8

## issue tracker for Kallithea (leave blank to disable, absent for default)

#bugtracker = https://bitbucket.org/conservancy/kallithea/issues

## issue tracking mapping for commits messages

## comment out issue_pat, issue_server, issue_prefix to enable

## pattern to get the issues from commit messages

## default one used here is #<numbers> with a regex passive group for `#`

## {id} will be all groups matched from this pattern

issue_pat = (?:\s*#)(\d+)

## server url to the issue, each {id} will be replaced with match

## fetched from the regex and {repo} is replaced with full repository name

## including groups {repo_name} is replaced with just name of repo

## prefix to add to link to indicate it's an url

## #314 will be replaced by <issue_prefix><id>

issue_prefix = #

## issue_pat, issue_server_link, issue_prefix can have suffixes to specify

## multiple patterns, to other issues server, wiki or others

## below an example how to create a wiki pattern

#issue_pat_wiki = (?:wiki-)(.+)

#issue_prefix_wiki = WIKI-

## instance-id prefix

## a prefix key for this instance used for cache invalidation when running

## multiple instances of kallithea, make sure it's globally unique for

## all running kallithea instances. Leave empty if you don't use it

instance_id =

## alternative return HTTP header for failed authentication. Default HTTP

## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with

## handling that. Set this variable to 403 to return HTTPForbidden

auth_ret_code =

## locking return code. When repository is locked return this HTTP code. 2XX

## codes don't break the transactions while 4XX codes do

lock_ret_code = 423

## allows to change the repository location in settings page

allow_repo_location_change = True

## allows to setup custom hooks in settings page

allow_custom_hooks_settings = True

####################################

        FilesController:raw,

        FilesController:archivefile

After this change, a Kallithea view can be accessed without login by adding a

GET parameter ``?api_key=<api_key>`` to the URL.

Exposing raw diffs is a good way to integrate with

third-party services like code review, or build farms that can download archives.

API access

++++++++++

Clients must send JSON encoded JSON-RPC requests::

    {

        "id: "<id>",

        "api_key": "<api_key>",

        "method": "<method_name>",

        "args": {"<arg_key>": "<arg_val>"}

    }

For example, to pull to a local "CPython" mirror using curl::

        --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

In general, provide

 - *id*, a value of any type, can be used to match the response with the request that it is replying to.

 - *api_key*, for authentication and permission validation.

 - *method*, the name of the method to call -- a list of available methods can be found below.

 - *args*, the arguments to pass to the method.

.. note::

    api_key can be found or set on the user account page.

The response to the JSON-RPC API call will always be a JSON structure::

    {

        "id": <id>,  # the id that was used in the request

        "result": <result>|null,  # JSON formatted result (null on error)

        "error": null|<error_message>  # JSON formatted error (null on success)

    }

All responses from the API will be ``HTTP/1.0 200 OK``. If an error occurs,

the reponse will have a failure description in *error* and

*result* will be null.

API client

++++++++++

Kallithea comes with a ``kallithea-api`` command line tool, providing a convenient

way to call the JSON-RPC API.

For example, to call ``get_repo``::

Oops, looks like we forgot to add an argument. Let's try again, now

providing the ``repoid`` as a parameter::

To avoid specifying ``apihost`` and ``apikey`` every time, run::

so you don't have to specify them every time.

API methods

+++++++++++

pull

----

Pull the given repo from remote location. Can be used to automatically keep

remote repos up to date.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repoid" : "<reponame or repo_id>"

              }

OUTPUT::

The main repository is hosted on Our Own Kallithea (aka OOK) at

https://kallithea-scm.org/repos/kallithea/, our self-hosted instance

of Kallithea.

For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The

issue tracker is for tracking bugs, not for support, discussion, or ideas --

please use the `mailing list`_ or :ref:`IRC <readme>` to reach the community.

We use Weblate_ to translate the user interface messages into languages other

than English. Join our project on `Hosted Weblate`_ to help us.

To register, you can use your Bitbucket or GitHub account. See :ref:`translations`

for more details.

Getting started

---------------

To get started with development::

        hg clone https://kallithea-scm.org/repos/kallithea

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        paster make-config Kallithea my.ini

        paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp

        paster serve my.ini --reload &

        firefox http://127.0.0.1:5000/

You can also start out by forking https://bitbucket.org/conservancy/kallithea

on Bitbucket_ and create a local clone of your own fork.

Running tests

-------------

After finishing your changes make sure all tests pass cleanly. You can run

the testsuite running ``nosetests`` from the project root, or if you use tox

run ``tox`` for Python 2.6--2.7 with multiple database test.

When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the

SQLite database specified there.

It is possible to avoid recreating the full test database on each invocation of

the tests, thus eliminating the initial delay. To achieve this, run the tests as::

    paster serve kallithea/tests/test.ini --pid-file=test.pid --daemon

    KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 nosetests

.. _index:

#######################

Kallithea Documentation

#######################

**Readme**

.. toctree::

   :maxdepth: 1

   readme

**Installation**

.. toctree::

   :maxdepth: 1

   overview

   installation

   installation_win

   installation_win_old

   installation_iis

   setup

**Usage**

.. toctree::

   :maxdepth: 1

   usage/general

   usage/vcs_support

   usage/locking

   usage/statistics

**Administrator's guide**

.. toctree::

   :maxdepth: 1

   usage/email

   usage/performance

   usage/backup

   usage/debugging

   usage/troubleshooting

**Development**

  contained inside the virtualenv (which also means you can have multiple

  installations side by side or remove it entirely by just removing the

  virtualenv directory) and does not require root privileges.

- :ref:`installation-without-virtualenv`: The alternative method of installing

  a Kallithea release is using standard pip. The package will be installed in

  the same location as all other Python packages you have ever installed. As a

  result, removing it is not as straightforward as with a virtualenv, as you'd

  have to remove its dependencies manually and make sure that they are not

  needed by other packages.

.. _installation-source:

Installation from repository source

-----------------------------------

To install Kallithea in a virtualenv_ using the stable branch of the development

repository, follow the instructions below::

        hg clone https://kallithea-scm.org/repos/kallithea -u stable

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

You can now proceed to :ref:`setup`.

To upgrade, simply update the repository with ``hg pull -u`` and restart the

server.

.. _installation-virtualenv:

Installing a released version in a virtualenv

---------------------------------------------

It is highly recommended to use a separate virtualenv_ for installing Kallithea.

This way, all libraries required by Kallithea will be installed separately from your

main Python installation and other applications and things will be less

problematic when upgrading the system or Kallithea.

An additional benefit of virtualenv_ is that it doesn't require root privileges.

- Assuming you have installed virtualenv_, create a new virtual environment

  for example, in `/srv/kallithea/venv`, using the virtualenv command::

    virtualenv /srv/kallithea/venv

    source /srv/kallithea/venv/bin/activate

.. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it

   will "activate" a shell that terminates immediately. It is also perfectly

   acceptable (and desirable) to create a virtualenv as a normal user.

- Make a folder for Kallithea data files, and configuration somewhere on the

  filesystem. For example::

    mkdir /srv/kallithea

- Go into the created directory and run this command to install Kallithea::

    pip install kallithea

  Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,

  extract it and run::

- This will install Kallithea together with pylons_ and all other required

  python libraries into the activated virtualenv.

You can now proceed to :ref:`setup`.

.. _installation-without-virtualenv:

Installing a released version without virtualenv

------------------------------------------------

For installation without virtualenv, 'just' use::

    pip install kallithea

Note that this method requires root privileges and will install packages

globally without using the system's package manager.

To install as a regular user in ``~/.local``, you can use::

    pip install --user kallithea

You can now proceed to :ref:`setup`.

with an identity that has read access to the Kallithea distribution.

The application pool does not need to be able to run any managed code. If you

are using a 32-bit Python installation, then you must enable 32-bit program in

the advanced settings for the application pool; otherwise Python will not be able

to run on the website and neither will Kallithea.

.. note::

    The application pool can be the same as an existing application pool,

    as long as the Kallithea requirements are met by the existing pool.

ISAPI handler

.............

The ISAPI handler can be generated using::

    paster install-iis my.ini --root=/

This will generate a ``dispatch.py`` file in the current directory that contains

the necessary components to finalize an installation into IIS. Once this file

has been generated, it is necessary to run the following command due to the way

that ISAPI-WSGI is made::

This accomplishes two things: generating an ISAPI compliant DLL file,

``_dispatch.dll``, and installing a script map handler into IIS for the

``--root`` specified above pointing to ``_dispatch.dll``.

The ISAPI handler is registered to all file extensions, so it will automatically

be the one handling all requests to the specified root. When the website starts

the ISAPI handler, it will start a thread pool managed wrapper around the paster

middleware WSGI handler that Kallithea runs within and each HTTP request to the

site will be processed through this logic henceforth.

Authentication with Kallithea using IIS authentication modules

..............................................................

The recommended way to handle authentication with Kallithea using IIS is to let

IIS handle all the authentication and just pass it to Kallithea.

To move responsibility into IIS from Kallithea, we need to configure Kallithea

to let external systems handle authentication and then let Kallithea create the

user automatically. To do this, access the administration's authentication page

and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is

added, enable it with the ``REMOTE_USER`` header and check *Clean username*.

Finally, save the changes on this page.

Switch to the administration's permissions page and disable anonymous access,

otherwise Kallithea will not attempt to use the authenticated user name. By

default, Kallithea will populate the list of users lazily as they log in. Either

disable external auth account activation and ensure that you pre-populate the

user database with an external tool, or set it to *Automatic activation of