r"""hg serve the Git world

This extension lets you serve Git users from a Mercurial world. After some
very basic setup, Git users can pull from *and push to* your repository
as if it were any other Git repository.

For a quick example::

  $ hg git-export
  $ hg serve

then in another terminal::

  $ git clone http://localhost:8000/  # or wherever 'hg serve' ran

Git pulling and pushing are protected by the same ACL as regular Mercurial
interactions through :hg:`serve`, with the same authentication mechanism.

This works atop the ``hggit`` extension, and (unlike ``hggit``) requires that
you have Git installed (maybe this will go away in a future version?).

Setup and configuration
-----------------------

Enable the ``hggit_serve`` extension in one of the many Mercurial configuration
files available to you.

Exporting the repository
^^^^^^^^^^^^^^^^^^^^^^^^

Serving a Git version of the repository requires that the Git version
be exported from the repository using ``hggit``. This generally exists for
a repository cloned from a Git source, but does not exist for a repository
created entirely within Mercurial. Once a repository has been exported to Git,
``hggit_serve`` will automatically update the Git version of the repository
every time new commits are added to the Mercurial side.

This may be an expensive operation the first time an export is performed,
but after the first export, further exports only have to add new revisions
and make incremental updates.

By default, ``hggit_serve`` will only export Git versions of repositories
that have already been :hg:`git-export`ed before. You can control this behavior
in :hg:`config`::

  [hggit-serve]

  auto-export = default
  # auto-export: when a repository is written to, update the Git export,
  # but only if one exists. You will have to run
  #
  #   hg git-export
  #
  # once on each repository you wish to make available to Git.

  auto-export = always
  # Whenever a repository is written to, export a Git copy of the repository,
  # even if one doesn't exist yet.

  auto-export = never
  # Never automatically export a Git copy of the repository, not even to update
  # the existing export. The Git version will only be updated when you run
  # hg git-export or otherwise interact with Git via hggit.

Handling branches
^^^^^^^^^^^^^^^^^

Git doesn't have an implicit ``tip`` revision like Mercurial does.
Instead, there is a HEAD reference which tells the client which version
to check out.

``hggit_serve`` will, by default, look in the following places to decide
what Git branch to use as the HEAD:

#. The currently active Mercurial bookmark.
#. The bookmark named ``@``. (See :hg:`bookmarks` for details.)
#. The repository ``tip``.

If ``@`` or the ``tip`` is used to select the active Git branch,
then ``hggit_serve`` needs to pick a branch name to use.
This can be configured with the ``default-branch`` setting.

  [hggit-serve]

  default-branch = main
  # Set what the name of the default branch to check out will be.
  # If unset, the name "default" will be used.
"""

from __future__ import annotations

from ._export import uipopulate
from ._http import uisetup
from ._ssh import cmdtable

#
# Interfacing with Mercurial
#

__version__ = '0.3.0'
testedwith = b'7.1 7.2'
minimumhgversion = b'7.1'


__all__ = (
    '__version__',
    'cmdtable',
    'minimumhgversion',
    'testedwith',
    'uipopulate',
    'uisetup',
)