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>

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::

.. _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

  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

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

# 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

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

        """

        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))

            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 '

    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)

    # 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

def action_logger(user, action, repo, ipaddr='', sa=None, commit=False):

    """

    Action logger for various actions made by users

    :param user: user that made this action, can be a unique username string or

        object containing user_id attribute

    :param action: action to log, should be on of predefined unique actions for

        easy translations

    :param repo: string name of repository or object containing repo_id,

        that action was made on

    :param ipaddr: optional ip address from what the action was made

    :param sa: optional sqlalchemy session

    """

    if not sa:

        sa = meta.Session()

    try:

        if hasattr(user, 'user_id'):

            user_obj = user

        elif isinstance(user, basestring):

            user_obj = User.get_by_username(user)

        else:

        if hasattr(repo, 'repo_id'):

            repo_obj = Repository.get(repo.repo_id)

            repo_name = repo_obj.repo_name

        elif  isinstance(repo, basestring):

            repo_name = repo.lstrip('/')

            repo_obj = Repository.get_by_repo_name(repo_name)

        else:

            repo_obj = None

            repo_name = ''

        user_log = UserLog()

        user_log.user_id = user_obj.user_id

        user_log.action = safe_unicode(action)

        user_log.repository = repo_obj

        user_log.repository_name = repo_name

        user_log.action_date = datetime.datetime.now()

        user_log.user_ip = ipaddr

        sa.add(user_log)

        log.info(

            'Adding user %s, action %s on %s' % (user_obj, action,

    :param base_path:

    """

    full_path = os.path.join(safe_str(base_path), safe_str(repos_group_name))

    # check if it's not a repo

    if is_valid_repo(repos_group_name, base_path):

        return False

    try:

        # we need to check bare git repos at higher level

        # since we might match branches/hooks/info/objects or possible

        # other things inside bare git repo

        get_scm(os.path.dirname(full_path))

        return False

    except VCSError:

        pass

    # check if it's a valid path

    if os.path.isdir(full_path):

        return True

    return False

    while True:

        ok = raw_input(prompt)

        if ok in ('y', 'ye', 'yes'):

            return True

        if ok in ('n', 'no', 'nop', 'nope'):

            return False

        retries = retries - 1

        if retries < 0:

            raise IOError

        print complaint

#propagated from mercurial documentation

ui_sections = ['alias', 'auth',

                'decode/encode', 'defaults',

                'diff', 'email',

                'extensions', 'format',

                'merge-patterns', 'merge-tools',

                'hooks', 'http_proxy',

                'smtp', 'patch',

                'paths', 'profiling',

                'server', 'trusted',

                'ui', 'web', ]

def make_ui(read_from='file', path=None, checkpaths=True, clear_session=True):

    """

    A function that will read python rc files or database

    and make an mercurial ui object from read options

    :param path: path to mercurial config file

    :param checkpaths: check the path

    :param read_from: read from 'file' or 'db'

    """

    baseui = ui.ui()

    # clean the baseui object

    baseui._ocfg = config.config()

    baseui._ucfg = config.config()

    baseui._tcfg = config.config()

    if read_from == 'file':

        if not os.path.isfile(path):

            return False

        log.debug('reading hgrc from %s' % path)

        cfg = config.config()

        cfg.read(path)

        for section in ui_sections:

            for k, v in cfg.items(section):

                log.debug('settings ui from file[%s]%s:%s' % (section, k, v))

                baseui.setconfig(section, k, v)

    elif read_from == 'db':

        sa = meta.Session()

        ret = sa.query(RhodeCodeUi)\

            .options(FromCache("sql_cache_short", "get_hg_ui_settings"))\

            .all()

        hg_ui = ret

        for ui_ in hg_ui:

            if ui_.ui_active:

                log.debug('settings ui from db[%s]%s:%s', ui_.ui_section,

                          ui_.ui_key, ui_.ui_value)

                baseui.setconfig(ui_.ui_section, ui_.ui_key, ui_.ui_value)

            if ui_.ui_key == 'push_ssl':

                # force set push_ssl requirement to False, rhodecode

                # handles that

            rgm._create_default_perms(group)

            sa.flush()

        parent = group

    return group

def repo2db_mapper(initial_repo_list, remove_obsolete=False,

                   install_git_hook=False):

    """

    maps all repos given in initial_repo_list, non existing repositories

    are created, if remove_obsolete is True it also check for db entries

    that are not in initial_repo_list and removes them.

    :param initial_repo_list: list of repositories found by scanning methods

    :param remove_obsolete: check for obsolete entries in database

    :param install_git_hook: if this is True, also check and install githook

        for a repo if missing

    """

    from rhodecode.model.repo import RepoModel

    from rhodecode.model.scm import ScmModel

    sa = meta.Session()

    rm = RepoModel()

    user = sa.query(User).filter(User.admin == True).first()

    if user is None:

    added = []

#    # clear cache keys

#    log.debug("Clearing cache keys now...")

#    CacheInvalidation.clear_cache()

#    sa.commit()

    for name, repo in initial_repo_list.items():

        group = map_groups(name)

        db_repo = rm.get_by_repo_name(name)

        # found repo that is on filesystem not in RhodeCode database

        if not db_repo:

            added.append(name)

            desc = (repo.description

                    if repo.description != 'unknown'

                    else '%s repository' % name)

            new_repo = rm.create_repo(

                repo_name=name,

                repo_type=repo.alias,

                description=desc,

                repos_group=getattr(group, 'group_id', None),

                owner=user,

                just_db=True

            )

            # we added that repo just now, and make sure it has githook

            # installed

            if new_repo.repo_type == 'git':

                ScmModel().install_git_hook(new_repo.scm_instance)

        elif install_git_hook:

            if db_repo.repo_type == 'git':

                ScmModel().install_git_hook(db_repo.scm_instance)

        # during starting install all cache keys for all repositories in the

        # system, this will register all repos and multiple instances

        key, _prefix, _org_key = CacheInvalidation._get_key(name)

        CacheInvalidation._get_or_create_key(key, _prefix, _org_key, commit=False)

    sa.commit()

    removed = []

    if remove_obsolete:

        # remove from database those repositories that are not in the filesystem

        for repo in sa.query(Repository).all():

            if repo.repo_name not in initial_repo_list.keys():

                          repo.repo_name)

                try:

                    sa.delete(repo)

                    sa.commit()

                    removed.append(repo.repo_name)

                except:

                    #don't hold further removals on error

                    log.error(traceback.format_exc())

                    sa.rollback()

    return added, removed

# set cache regions for beaker so celery can utilise it

def add_cache(settings):

    cache_settings = {'regions': None}

    for key in settings.keys():

        for prefix in ['beaker.cache.', 'cache.']:

            if key.startswith(prefix):

                name = key.split(prefix)[1].strip()

                cache_settings[name] = settings[key].strip()

    if cache_settings['regions']:

        for region in cache_settings['regions'].split(','):

            region = region.strip()

    def update_parser(self):

        """

        Abstract method.  Allows for the class's parser to be updated

        before the superclass's `run` method is called.  Necessary to

        allow options/arguments to be passed through to the underlying

        celery command.

        """

        raise NotImplementedError("Abstract Method.")

    def bootstrap_config(self, conf):

        """

        Loads the pylons configuration.

        """

        from pylons import config as pylonsconfig

        self.path_to_ini_file = os.path.realpath(conf)

        conf = paste.deploy.appconfig('config:' + self.path_to_ini_file)

        pylonsconfig.init_app(conf.global_conf, conf.local_conf)

def check_git_version():

    """

    Checks what version of git is installed in system, and issues a warning