.. -*- mode: rst -*-

====================================
Mercurial Dynamic Username
====================================

Use different commit username per directory tree.

With this extension you may commit as ``John Smith
<john.smith@serious.com>`` in repositories below ``~/work``, and as ``Johny
<fastjohny@fantasy.net>`` in code under ``~/hobby`` - and set this
rule once, in ``~/.hgrc``.

Example
=====================

Install the extension as described below.

Write in your ``~/.hgrc``::

    [extensions]
    mercurial_dynamic_username =

    [dynamic_username]
    work.location = ~/work
    work.username = John Smith <john.smith@serious.com>
    hobby.location = ~/hobby ~/blogging
    hobby.username = Johny <fastjohny@fantasy.net>

and just commit. In any repository placed below ``~/work`` you will commit as
``John Smith``, in repos below ``~/hobby`` as ``Johny``, elsewhere default
setting (``username`` from ``[ui]``) will be used.

Configuration syntax
=====================

All settings are defined in ``[dynamic_username]`` section, and have
the following form::

    «somelabel».location = «list of directory names»
    «somelabel».username = «username used there»

Labels are used only to join pairs of those settings together.

Directory names specified in ``.location`` are space or colon
separated, and can be quoted. Repository matches the rule if it
belongs to the directory tree(s) specified here. Tildas (``~/..`` and
``~john/...``) are properly expanded.

Usernames have the same syntax as standard ``username``.

Defining ``.location`` without paired ``.username`` asks extension to
revert to standard username, for example::

    [ui]
    username = Jake <jake@loose.net>

    [dynamic_username]
    work.location = ~/work
    work.username = John Smith <john.smith@serious.com>
    open.location = ~/work/open-source

will commit as ``John Smith`` in ``~/work/libs/veryimportant``, but
will revert to default ``Jake`` in ``~/work/open-source/libshared``.

Match priority
==================================================

If more than one location matches repository, longest one is used
(like in the ``open-source`` example above). *Longest* is selected
using actual canonical path after tilda expansion (``~/work/sth`` is
longer than ``/home/littlejohny/work``).

Dynamic usernames currently always win against ``[ui]``-section
``username``, even if the latter is defined in per-repository
``.hg/hgrc``. I would gladly give priority to the latter, but I have
no idea how to detect that without re-parsing the configuration.

Testing configuration
==================================================

You can test your configuration by callling::

    hg showconfig ui.username

(results should vary depending on the current working directory).
Handy way to compare::

    hg --cwd ~/work/libs/acme  showconfig ui.username
    hg --cwd ~/hobby/blogging  showconfig ui.username

Installation
=================================================

Linux/Unix (from PyPI)
~~~~~~~~~~~~~~~~~~~~~~

If you have working ``pip`` or ``easy_install``::

    pip install --user mercurial_dynamic_username

or maybe::

    sudo pip install mercurial_dynamic_username

(or use ``easy_install`` instead of ``pip``). Then activate by::

    [extensions]
    mercurial_dynamic_username =

To upgrade, repeat the same command with ``--upgrade`` option, for
example::

    pip install --user --upgrade mercurial_dynamic_username

Linux/Unix (from source)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you don't have ``pip``, or wish to follow development more closely:

- clone both this repository and `mercurial_extension_utils`_ and put
  them in the same directory, for example::

    cd ~/sources
    hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/
    hg clone https://bitbucket.org/Mekk/mercurial-dynamic_username/

- update to newest tags,

- activate by::

    [extensions]
    mercurial_dynamic_username = ~/sources/mercurial-dynamic_username/mercurial_dynamic_username.py

To upgrade, pull and update.

Note that directory names matter. See `mercurial_extension_utils`_ for
longer description of this kind of installation.

Windows
~~~~~~~~~~~~~~~~~~~~~~~

If you have any Python installed, you may install with ``pip``::

    pip install mercurial_dynamic_username

Still, as Mercurial (whether taken from TortoiseHg_, or own package)
uses it's own bundled Python, you must activate by specifying the path::

    [extensions]
    mercurial_dynamic_username = C:/Python27/Lib/site-packages/mercurial_dynamic_username.py
    ;; Or wherever pip installed it

To upgrade to new version::

    pip --upgrade mercurial_dynamic_username

If you don't have any Python, clone repositories::

    cd c:\hgplugins
    hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/
    hg clone https://bitbucket.org/Mekk/mercurial-dynamic_username/

update to tagged versions and activate by path::

    [extensions]
    mercurial_dynamic_username = C:/hgplugins/mercurial-dynamic_username/mercurial_dynamic_username.py
    ;; Or wherever you cloned

See `mercurial_extension_utils`_ documentation for more details on
Windows installation. 

.. note::

   Directory names matter. If ``mercurial_dynamic_username.py`` can't find
   ``mercurial_extension_utils.py`` in system path, it looks for it in
   its own directory, in ``../mercurial_extension_utils``, and in
   ``../extension_utils``.


History
==================================================

See `HISTORY.txt`_

Development, bug reports, enhancement suggestions
===================================================

Development is tracked on BitBucket, see 
http://bitbucket.org/Mekk/mercurial-dynamic_username/

Use BitBucket issue tracker for bug reports and enhancement
suggestions.

Additional notes
================

Information about this extension is also available
on Mercurial Wiki: http://mercurial.selenic.com/wiki/DynamicUsernameExtension

.. _Mercurial: http://mercurial.selenic.com
.. _HISTORY.txt: http://bitbucket.org/Mekk/mercurial-dynamic_username/src/tip/HISTORY.txt
.. _mercurial_extension_utils: https://bitbucket.org/Mekk/mercurial-extension_utils/
.. _TortoiseHg: http://tortoisehg.bitbucket.org/
