--- a/src/hgext3rd/hggit_serve/__init__.py	Thu Feb 19 01:13:56 2026 -0500
+++ b/src/hgext3rd/hggit_serve/__init__.py	Fri Feb 20 21:05:31 2026 -0500
@@ -13,13 +13,78 @@
 
   $ 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
------
+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]
 
-TODO
+  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

--- a/src/hgext3rd/hggit_serve/_export.py	Thu Feb 19 01:13:56 2026 -0500
+++ b/src/hgext3rd/hggit_serve/_export.py	Fri Feb 20 21:05:31 2026 -0500
@@ -151,15 +151,25 @@
 # Hooks
 #
 
+_AX_ALWAYS = b'always'
+_AX_DEFAULT = b'default'
+_AX_NEVER = b'never'
+
 
 def _export_hook(ui: hgui.ui, repo: hgrepo.IRepo, **__: object) -> None:
     """Maybe exports the repository to get after we get new revs."""
     if not is_gitty(repo):
         return
     auto_export = ui.config(b'hggit-serve', b'auto-export')
-    if auto_export == b'never':
+    if auto_export == _AX_NEVER:
         return
-    if auto_export == b'always' or git_handler.has_gitrepo(repo):
+    if auto_export == _AX_ALWAYS or git_handler.has_gitrepo(repo):
+        if auto_export not in (None, _AX_ALWAYS, _AX_DEFAULT):
+            ui.warn(
+                b'unrecognized auto-export setting %s; using %s',
+                auto_export,
+                _AX_DEFAULT,
+            )
         if _is_importing(repo):
             ui.note(b'currently importing revs from git; not exporting\n')
             return