Mercurial > hg-git-serve

annotate src/hgext3rd/hggit_serve/__init__.py @ 17:a70f387ab3cd default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix formatting in documentation.
author Paul Fisher <paul@pfish.zone>
date Fri, 20 Feb 2026 21:12:40 -0500
parents 959ef686193f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
1 r"""hg serve the Git world
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
2
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
3 This extension lets you serve Git users from a Mercurial world. After some
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
4 very basic setup, Git users can pull from *and push to* your repository
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
5 as if it were any other Git repository.
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
6
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
7 For a quick example::
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
8
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
9 $ hg git-export
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
10 $ hg serve
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
11
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
12 then in another terminal::
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
14 $ git clone http://localhost:8000/ # or wherever 'hg serve' ran
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
15
14
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
16 Git pulling and pushing are protected by the same ACL as regular Mercurial
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
17 interactions through :hg:`serve`, with the same authentication mechanism.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
18
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
19 This works atop the ``hggit`` extension, and (unlike ``hggit``) requires that
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
20 you have Git installed (maybe this will go away in a future version?).
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
21
14
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
22 Setup and configuration
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
23 -----------------------
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
24
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
25 Enable the ``hggit_serve`` extension in one of the many Mercurial configuration
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
26 files available to you.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
27
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
28 Exporting the repository
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
29 ^^^^^^^^^^^^^^^^^^^^^^^^
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
30
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
31 Serving a Git version of the repository requires that the Git version
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
32 be exported from the repository using ``hggit``. This generally exists for
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
33 a repository cloned from a Git source, but does not exist for a repository
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
34 created entirely within Mercurial. Once a repository has been exported to Git,
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
35 ``hggit_serve`` will automatically update the Git version of the repository
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
36 every time new commits are added to the Mercurial side.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
37
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
38 This may be an expensive operation the first time an export is performed,
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
39 but after the first export, further exports only have to add new revisions
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
40 and make incremental updates.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
41
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
42 By default, ``hggit_serve`` will only export Git versions of repositories
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
43 that have already been :hg:`git-export`ed before. You can control this behavior
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
44 in :hg:`config`::
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
45
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
46 [hggit-serve]
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
47
14
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
48 auto-export = default
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
49 # auto-export: when a repository is written to, update the Git export,
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
50 # but only if one exists. You will have to run
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
51 #
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
52 # hg git-export
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
53 #
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
54 # once on each repository you wish to make available to Git.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
55
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
56 auto-export = always
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
57 # Whenever a repository is written to, export a Git copy of the repository,
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
58 # even if one doesn't exist yet.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
59
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
60 auto-export = never
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
61 # Never automatically export a Git copy of the repository, not even to update
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
62 # the existing export. The Git version will only be updated when you run
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
63 # hg git-export or otherwise interact with Git via hggit.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
64
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
65 Handling branches
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
66 ^^^^^^^^^^^^^^^^^
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
67
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
68 Git doesn't have an implicit ``tip`` revision like Mercurial does.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
69 Instead, there is a HEAD reference which tells the client which version
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
70 to check out.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
71
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
72 ``hggit_serve`` will, by default, look in the following places to decide
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
73 what Git branch to use as the HEAD:
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
74
17
a70f387ab3cd Fix formatting in documentation.
Paul Fisher <paul@pfish.zone>
parents: 14
diff changeset
75 1. The currently active Mercurial bookmark.
a70f387ab3cd Fix formatting in documentation.
Paul Fisher <paul@pfish.zone>
parents: 14
diff changeset
76 2. The bookmark named ``@``. (See :hg:`bookmarks` for details.)
a70f387ab3cd Fix formatting in documentation.
Paul Fisher <paul@pfish.zone>
parents: 14
diff changeset
77 3. The repository ``tip``.
14
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
78
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
79 If ``@`` or the ``tip`` is used to select the active Git branch,
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
80 then ``hggit_serve`` needs to pick a branch name to use.
17
a70f387ab3cd Fix formatting in documentation.
Paul Fisher <paul@pfish.zone>
parents: 14
diff changeset
81 This can be configured with the ``default-branch`` setting::
14
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
82
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
83 [hggit-serve]
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
84
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
85 default-branch = main
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
86 # Set what the name of the default branch to check out will be.
959ef686193f Add user-facing documentation.
Paul Fisher <paul@pfish.zone>
parents: 13
diff changeset
87 # If unset, the name "default" will be used.
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
88 """
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
89
1
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
90 from __future__ import annotations
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
91
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
92 from ._export import uipopulate
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
93 from ._http import uisetup
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
94 from ._ssh import cmdtable
1
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
95
8
fe3c9fae4d4d Add support for pushes, and improve authentication.
Paul Fisher <paul@pfish.zone>
parents: 7
diff changeset
96 #
1
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
97 # Interfacing with Mercurial
8
fe3c9fae4d4d Add support for pushes, and improve authentication.
Paul Fisher <paul@pfish.zone>
parents: 7
diff changeset
98 #
1
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
99
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
100 __version__ = '0.3.0'
6
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
101 testedwith = b'7.1 7.2'
8
fe3c9fae4d4d Add support for pushes, and improve authentication.
Paul Fisher <paul@pfish.zone>
parents: 7
diff changeset
102 minimumhgversion = b'7.1'
1
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
103
a39dd69b8972 Create a more-or-less real package and make it work (?)
Paul Fisher <paul@pfish.zone>
parents: 0
diff changeset
104
6
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
105 __all__ = (
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
106 '__version__',
13
00bdfac5416c Create Git SSH commands and add some documentation. Also cleanup.
Paul Fisher <paul@pfish.zone>
parents: 12
diff changeset
107 'cmdtable',
8
fe3c9fae4d4d Add support for pushes, and improve authentication.
Paul Fisher <paul@pfish.zone>
parents: 7
diff changeset
108 'minimumhgversion',
6
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
109 'testedwith',
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
110 'uipopulate',
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
111 'uisetup',
7113e0ac3662 fix refs on git-export; clean up how gitserve export works.
Paul Fisher <paul@pfish.zone>
parents: 5
diff changeset
112 )