List of contributors to RhodeCode project:

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

    Lukasz Balcerzak <lukaszbalcerzak@gmail.com>

    Jason Harris <jason@jasonfharris.com>

    Thayne Harbaugh  <thayne@fusionio.com>

    cejones <>

    Thomas Waldmann <tw-public@gmx.de>

    Lorenzo M. Catucci <lorenzo@sancho.ccd.uniroma2.it>

    Dmitri Kuznetsov <>

    Jared Bunting <jared.bunting@peachjean.com>

    Steve Romanow <slestak989@gmail.com>

    Augosto Hermann <augusto.herrmann@planejamento.gov.br>    

    Ankit Solanki <ankit.solanki@gmail.com>    

    Liad Shani <liadff@gmail.com>

    Les Peabody <lpeabody@gmail.com>

    Jonas Oberschweiber <jonas.oberschweiber@d-velop.de>

    Matt Zuba <matt.zuba@goodwillaz.org>

    Aras Pranckevicius <aras@unity3d.com>

    Tony Bussieres <t.bussieres@gmail.com>

    Erwin Kroon <e.kroon@smartmetersolutions.nl>

    nansenat16 <nansenat16@null.tw>

    Vincent Duvert <vincent@duvert.net>

    Takumi IINO <trot.thunder@gmail.com>

    Indra Talip <indra.talip@gmail.com>

    James Rhodes <jrhodes@redpointsoftware.com.au>

    Dominik Ruf <dominikruf@gmail.com>

    xpol <xpolife@gmail.com>

    Vincent Caron <vcaron@bearstech.com>

    Zachary Auclair <zach101@gmail.com>

    Stefan Engel <mail@engel-stefan.de>

    id : <id_given_in_input>

    result : None if group not exist

             {

               "users_group_id" : "<id>",

               "group_name" :     "<groupname>",

               "active":          "<bool>",

               "members" :  [

                              { 

                                "user_id" :  "<user_id>",

                                "username" : "<username>",

                                "firstname": "<firstname>",

                                "lastname" : "<lastname>",

                                "email" :    "<email>",

                                "emails":    "<list_of_all_additional_emails>",

                                "active" :   "<bool>",

                                "admin" :    "<bool>",

                                "ldap_dn" :  "<ldap_dn>",

                                "last_login": "<last_login>",

                              },

                              …

                            ]

             }

    error : null

get_users_groups

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

Lists all existing users groups. This command can be executed only using 

api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users_groups"

    args :    { }

OUTPUT::

    id : <id_given_in_input>

    result : [

               {

               "users_group_id" : "<id>",

               "group_name" :     "<groupname>",

               "active":          "<bool>",

               },

               …

              ]

    error : null

create_users_group

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

Creates new users group. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_users_group"

    args:     {

                "group_name":  "<groupname>",

                "active":"<bool> = Optional(True)"

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "msg": "created new users group `<groupname>`",

              "users_group": {

                     "users_group_id" : "<id>",

                     "group_name" :     "<groupname>",

                     "active":          "<bool>",

               },

            }

    error:  null

add_user_to_users_group

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

Adds a user to a users group. If user exists in that group success will be 

`false`. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "add_user_users_group"

    args:     {

                "usersgroupid" : "<users group id or name>",

                "userid" : "<user_id or username>",

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "success": True|False # depends on if member is in group

              "msg": "added member `<username>` to users group `<groupname>` | 

                      User is already in that group"

            }

    error:  null

remove_user_from_users_group

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

Removes a user from a users group. If user is not in given group success will

be `false`. This command can be executed only 

using api_key belonging to user with admin rights

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "remove_user_from_users_group"

    args:     {

.. _changelog:

=========

Changelog

=========

1.4.4 (**2012-10-08**)

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

news

++++

- obfuscate db password in logs for engine connection string

- #574 Show pull request status also in shortlog (if any)

- remember selected tab in my account page

- Bumped mercurial version to 2.3.2

fixes

+++++

- Add git version detection to warn users that Git used in system is to

  old. Ref #588 - also show git version in system details in settings page

- fixed files quick filter links

- #590 Add GET flag that controls the way the diff are generated, for pull

  requests we want to use non-bundle based diffs, That are far better for

  doing code reviews. The /compare url still uses bundle compare for full

  comparison including the incoming changesets

- Fixed #585, checks for status of revision where to strict, and made

  opening pull request with those revision impossible due to previously set

  status. Checks now are made also for the repository.

- fixes #591 git backend was causing encoding errors when handling binary

  files - added a test case for VCS lib tests

1.4.3 (**2012-09-28**)

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

news

++++

- #558 Added config file to hooks extra data

- bumped mercurial version to 2.3.1

- #518 added possibility of specifying multiple patterns for issues

- update codemirror to latest version

fixes

+++++

- fixed #570 explicit users group permissions can overwrite owner permissions

- fixed #578 set proper PATH with current Python for Git

  hooks to execute within same Python as RhodeCode 

- fixed issue with Git bare repos that ends with .git in name

1.4.2 (**2012-09-12**)

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

news

++++

- added option to menu to quick lock/unlock repository for users that have

  write access to

- Implemented permissions for writing to repo

  groups. Now only write access to group allows to create a repostiory

  within that group

- #565 Add support for {netloc} and {scheme} to alternative_gravatar_url

- updated translation for zh_CN 

fixes

+++++

- fixed visual permissions check on repos groups inside groups

- fixed issues with non-ascii search terms in search, and indexers

- fixed parsing of page number in GET parameters

- fixed issues with generating pull-request overview for repos with

  bookmarks and tags, also preview doesn't loose chosen revision from

  select dropdown

1.4.1 (**2012-09-07**)

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

news

postgresql, sqlite and mysql databases. Create the database by running

the following command::

    paster setup-rhodecode production.ini

This will prompt you for a "root" path. This "root" path is the location where

RhodeCode will store all of its repositories on the current machine. After

entering this "root" path ``setup-rhodecode`` will also prompt you for a username 

and password for the initial admin account which ``setup-rhodecode`` sets 

up for you.

setup process can be fully automated, example for lazy::

    paster setup-rhodecode production.ini --user=marcink --password=secret --email=marcin@rhodecode.org --repos=/home/marcink/my_repos

- The ``setup-rhodecode`` command will create all of the needed tables and an 

  admin account. When choosing a root path you can either use a new empty 

  location, or a location which already contains existing repositories. If you

  choose a location which contains existing repositories RhodeCode will simply 

  add all of the repositories at the chosen location to it's database. 

  (Note: make sure you specify the correct path to the root).

- Note: the given path for mercurial_ repositories **must** be write accessible

  for the application. It's very important since the RhodeCode web interface 

  will work without write access, but when trying to do a push it will 

  eventually fail with permission denied errors unless it has write access.

You are now ready to use RhodeCode, to run it simply execute::

    paster serve production.ini

- This command runs the RhodeCode server. The web app should be available at the 

  127.0.0.1:5000. This ip and port is configurable via the production.ini 

  file created in previous step

- Use the admin account you created above when running ``setup-rhodecode`` 

  to login to the web app.

- The default permissions on each repository is read, and the owner is admin. 

  Remember to update these if needed.

- In the admin panel you can toggle ldap, anonymous, permissions settings. As

  well as edit more advanced options on users and repositories

Optionally users can create `rcextensions` package that extends RhodeCode

functionality. To do this simply execute::

    paster make-rcext production.ini

This will create `rcextensions` package in the same place that your `ini` file

lives. With `rcextensions` it's possible to add additional mapping for whoosh, 

Please see the `__init__.py` file inside `rcextensions` package 

for more details.

Using RhodeCode with SSH

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

RhodeCode currently only hosts repositories using http and https. (The addition

of ssh hosting is a planned future feature.) However you can easily use ssh in

parallel with RhodeCode. (Repository access via ssh is a standard "out of

the box" feature of mercurial_ and you can use this to access any of the

repositories that RhodeCode is hosting. See PublishingRepositories_)

RhodeCode repository structures are kept in directories with the same name 

as the project. When using repository groups, each group is a subdirectory.

This allows you to easily use ssh for accessing repositories.

In order to use ssh you need to make sure that your web-server and the users 

login accounts have the correct permissions set on the appropriate directories.

(Note that these permissions are independent of any permissions you have set up

using the RhodeCode web interface.)

If your main directory (the same as set in RhodeCode settings) is for example

set to **/home/hg** and the repository you are using is named `rhodecode`, then

to clone via ssh you should run::

    hg clone ssh://user@server.com/home/hg/rhodecode

Using other external tools such as mercurial-server_ or using ssh key based

authentication is fully supported.

Note: In an advanced setup, in order for your ssh access to use the same

permissions as set up via the RhodeCode web interface, you can create an

authentication hook to connect to the rhodecode db and runs check functions for

permissions against that.

Setting up Whoosh full text search

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

Starting from version 1.1 the whoosh index can be build by using the paster

command ``make-index``. To use ``make-index`` you must specify the configuration

file that stores the location of the index. You may specify the location of the 

repositories (`--repo-location`).  If not specified, this value is retrieved 

from the RhodeCode database.  This was required prior to 1.2.  Starting from 

version 1.2 it is also possible to specify a comma separated list of 

repositories (`--index-only`) to build index only on chooses repositories 

skipping any other found in repos location

# Additional mappings that are not present in the pygments lexers

# used for building stats

# format is {'ext':['Names']} eg. {'py':['Python']} note: there can be

# more than one name for extension

# NOTE: that this will overide any mappings in LANGUAGES_EXTENSIONS_MAP

# build by pygments

EXTRA_MAPPINGS = {}

#==============================================================================

# WHOOSH INDEX EXTENSIONS

#==============================================================================

# if INDEX_EXTENSIONS is [] it'll use pygments lexers extensions by default.

# To set your own just add to this list extensions to index with content

INDEX_EXTENSIONS = []

# additional extensions for indexing besides the default from pygments

# those get's added to INDEX_EXTENSIONS

EXTRA_INDEX_EXTENSIONS = []

#==============================================================================

# POST CREATE REPOSITORY HOOK

#==============================================================================

# this function will be executed after each repository is created

def _crhook(*args, **kwargs):

    """

    Post create repository HOOK

    kwargs available:

     :param repo_name:

     :param repo_type:

     :param description:

     :param private:

     :param created_on:

     :param enable_downloads:

     :param repo_id:

     :param user_id:

     :param enable_statistics:

     :param clone_uri:

     :param fork_id:

     :param group_id:

     :param created_by:

    """

    return 0

CREATE_REPO_HOOK = _crhook

#==============================================================================

# POST PUSH HOOK

#==============================================================================

# this function will be executed after each push it's runned after the build-in

# hook that rhodecode uses for logging pushes

def _pushhook(*args, **kwargs):

    """

    Post push hook

    kwargs available:

      :param username: name of user who pushed

      :param ip: ip of who pushed

      :param action: pull

      :param repository: repository name

      :param pushed_revs: generator of pushed revisions

    """

    return 0

PUSH_HOOK = _pushhook

#==============================================================================

# POST PULL HOOK

#==============================================================================

# this function will be executed after each push it's runned after the build-in

# hook that rhodecode uses for logging pushes

def _pullhook(*args, **kwargs):

    """

    Post pull hook

    kwargs available::

      :param username: name of user who pulled

      :param ip: ip of who pushed

      :param action: pull

      :param repository: repository name

    """

    return 0

PULL_HOOK = _pullhook

        if not repo:

            h.flash(_('%s repository is not mapped to db perhaps'

                      ' it was moved or renamed  from the filesystem'

                      ' please run the application again'

                      ' in order to rescan repositories') % repo_name,

                      category='error')

            return redirect(url('home'))

        try:

            action_logger(self.rhodecode_user, 'user_deleted_repo',

                              repo_name, self.ip_addr, self.sa)

            repo_model.delete(repo)

            invalidate_cache('get_repo_cached_%s' % repo_name)

            h.flash(_('deleted repository %s') % repo_name, category='success')

            Session().commit()

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('An error occurred during deletion of %s') % repo_name,

                    category='error')

        return redirect(url('home'))

    @HasRepoPermissionAnyDecorator('repository.write', 'repository.admin')

    def toggle_locking(self, repo_name):

        """

        Toggle locking of repository by simple GET call to url

        :param repo_name:

        """

        try:

            repo = Repository.get_by_repo_name(repo_name)

            if repo.enable_locking:

                if repo.locked[0]:

                    Repository.unlock(repo)

                    action = _('unlocked')

                else:

                    Repository.lock(repo, c.rhodecode_user.user_id)

                    action = _('locked')

                h.flash(_('Repository has been %s') % action,

                        category='success')

        except Exception, e:

            log.error(traceback.format_exc())

            h.flash(_('An error occurred during unlocking'),

                    category='error')

        return redirect(url('summary_home', repo_name=repo_name))

        log.info('creating default user')

        # create default user for handling default permissions.

        UserModel().create_or_update(username='default',

                              password=str(uuid.uuid1())[:8],

                              email='anonymous@rhodecode.org',

                              firstname='Anonymous', lastname='User')

    def create_permissions(self):

        # module.(access|create|change|delete)_[name]

        # module.(none|read|write|admin)

        for p in Permission.PERMS:

            if not Permission.get_by_key(p[0]):

                new_perm = Permission()

                new_perm.permission_name = p[0]

                new_perm.permission_longname = p[0]

                self.sa.add(new_perm)

    def populate_default_permissions(self):

        log.info('creating default user permissions')

        default_user = User.get_by_username('default')

        for def_perm in User.DEFAULT_PERMISSIONS:

            perm = self.sa.query(Permission)\

             .filter(Permission.permission_name == def_perm)\

             .scalar()

            if not perm:

                raise Exception(

                  'CRITICAL: permission %s not found inside database !!'

                  % def_perm

                )

            if not UserToPerm.query()\

                .filter(UserToPerm.permission == perm)\

                .filter(UserToPerm.user == default_user).scalar():

                reg_perm = UserToPerm()

                reg_perm.user = default_user

                reg_perm.permission = perm

                self.sa.add(reg_perm)

    def finish(self):

        """

        Function executed at the end of setup

        """

        if not __py_version__ >= (2, 6):

            notify('Python2.5 detected, please switch '

                   'egg:waitress#main -> egg:Paste#http '

# -*- coding: utf-8 -*-

"""

    rhodecode.lib.hooks

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

    Hooks runned by rhodecode

    :created_on: Aug 6, 2010

    :author: marcink

    :copyright: (C) 2010-2012 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

import os

import sys

import binascii

from inspect import isfunction

from mercurial.scmutil import revrange

from mercurial.node import nullrev

from rhodecode.lib import helpers as h

from rhodecode.lib.utils import action_logger

from rhodecode.lib.vcs.backends.base import EmptyChangeset

from rhodecode.lib.compat import json

from rhodecode.lib.exceptions import HTTPLockedRC

from rhodecode.lib.utils2 import safe_str

from rhodecode.model.db import Repository, User

def _get_scm_size(alias, root_path):

    if not alias.startswith('.'):

        alias += '.'

    size_scm, size_root = 0, 0

    for path, dirs, files in os.walk(root_path):

        if path.find(alias) != -1:

            for f in files:

                try:

                    size_scm += os.path.getsize(os.path.join(path, f))

                except OSError:

                    pass

        else:

            for f in files:

                try:

                    size_root += os.path.getsize(os.path.join(path, f))

                except OSError:

                    pass

    size_scm_f = h.format_byte_size(size_scm)

    size_root_f = h.format_byte_size(size_root)

    size_total_f = h.format_byte_size(size_root + size_scm)

    return size_scm_f, size_root_f, size_total_f

def repo_size(ui, repo, hooktype=None, **kwargs):

    """

    Presents size of repository after push

    :param ui:

    :param repo:

    :param hooktype:

    """

    size_hg_f, size_root_f, size_total_f = _get_scm_size('.hg', repo.root)

    last_cs = repo[len(repo) - 1]

    msg = ('Repository size .hg:%s repo:%s total:%s\n'

           'Last revision is now r%s:%s\n') % (

        size_hg_f, size_root_f, size_total_f, last_cs.rev(), last_cs.hex()[:12]

    )

    sys.stdout.write(msg)

        node = kwargs['node']

        def get_revs(repo, rev_opt):

            if rev_opt:

                revs = revrange(repo, rev_opt)

                if len(revs) == 0:

                    return (nullrev, nullrev)

                return (max(revs), min(revs))

            else:

                return (len(repo) - 1, 0)

        stop, start = get_revs(repo, [node + ':'])

        h = binascii.hexlify

        revs = [h(repo[r].node()) for r in xrange(start, stop + 1)]

    elif scm == 'git':

        revs = kwargs.get('_git_revs', [])

        if '_git_revs' in kwargs:

            kwargs.pop('_git_revs')

    action = action % ','.join(revs)

    action_logger(username, action, repository, extras['ip'], commit=True)

    # extension hook call

    from rhodecode import EXTENSIONS

    callback = getattr(EXTENSIONS, 'PUSH_HOOK', None)

    if isfunction(callback):

        kw = {'pushed_revs': revs}

        kw.update(extras)

        callback(**kw)

    if make_lock is False:

        Repository.unlock(Repository.get_by_repo_name(repository))

        msg = 'Released lock on repo `%s`\n' % repository

        sys.stdout.write(msg)

    return 0

def log_create_repository(repository_dict, created_by, **kwargs):

    """

    Post create repository Hook. This is a dummy function for admins to re-use

    if needed. It's taken from rhodecode-extensions module and executed

    if present

    :param repository: dict dump of repository object

    :param created_by: username who created repository

    available keys of repository_dict:

     'repo_type',

     'description',

     'private',

     'created_on',

     'enable_downloads',

     'repo_id',

     'user_id',

     'enable_statistics',

     'clone_uri',

     'fork_id',

     'group_id',

     'repo_name'

    """

    from rhodecode import EXTENSIONS

    callback = getattr(EXTENSIONS, 'CREATE_REPO_HOOK', None)

    if isfunction(callback):

        kw = {}

        kw.update(repository_dict)

        kw.update({'created_by': created_by})

        kw.update(kwargs)

        return callback(**kw)

    return 0

handle_git_pre_receive = (lambda repo_path, revs, env:

    handle_git_receive(repo_path, revs, env, hook_type='pre'))

handle_git_post_receive = (lambda repo_path, revs, env:

    handle_git_receive(repo_path, revs, env, hook_type='post'))

def handle_git_receive(repo_path, revs, env, hook_type='post'):

    """

    A really hacky method that is runned by git post-receive hook and logs

    an push action together with pushed revisions. It's executed by subprocess

    thus needs all info to be able to create a on the fly pylons enviroment,

    connect to database and run the logging code. Hacky as sh*t but works.

    :param repo_path:

    :type repo_path:

    :param revs:

    :type revs:

    :param env:

    :type env:

    """

    from paste.deploy import appconfig

    from sqlalchemy import engine_from_config

    from rhodecode.config.environment import load_environment

    from rhodecode.model import init_model

    from rhodecode.model.db import RhodeCodeUi

    from rhodecode.lib.utils import make_ui

    extras = json.loads(env['RHODECODE_EXTRAS'])

    path, ini_name = os.path.split(extras['config'])

    conf = appconfig('config:%s' % ini_name, relative_to=path)

    load_environment(conf.global_conf, conf.local_conf)

    engine = engine_from_config(conf, 'sqlalchemy.db1.')

    init_model(engine)

    baseui = make_ui('db')

    # fix if it's not a bare repo

    if repo_path.endswith(os.sep + '.git'):

        repo_path = repo_path[:-5]

    repo = Repository.get_by_full_path(repo_path)

    if not repo: