Mirror/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2026-06-18 18:39:46 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist
2026-05-05 17:43:51 +02:00
parent 7731e799f4
commit b1357eb146
11 changed files with 378 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/git.html
+158 -28
View File
@@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Using Git Over Reticulum - Reticulum Network Stack 1.2.2 documentation</title>
<title>Git Over Reticulum - Reticulum Network Stack 1.2.2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -222,7 +222,7 @@
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Using Git Over Reticulum</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Git Over Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
@@ -261,8 +261,8 @@
</label>
</div>
<article role="main" id="furo-main-content">
<section id="using-git-over-reticulum">
<span id="git-main"></span><h1>Using Git Over Reticulum<a class="headerlink" href="#using-git-over-reticulum" title="Link to this heading"></a></h1>
<section id="git-over-reticulum">
<span id="git-main"></span><h1>Git Over Reticulum<a class="headerlink" href="#git-over-reticulum" title="Link to this heading"></a></h1>
<p>A set of utilities for distributed collaborative software development and publishing is included in RNS.</p>
<p>The system consists of two parts: The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node that hosts repositories, and the <code class="docutils literal notranslate"><span class="pre">git-remote-rns</span></code> helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: <code class="docutils literal notranslate"><span class="pre">rns://DESTINATION_HASH/group/repo</span></code>.</p>
<p>If you set a branch to track a Reticulum remote as the default upstream, you can simply use <code class="docutils literal notranslate"><span class="pre">git</span></code> as you normally would; all commands work transparently and as expected.</p>
@@ -290,7 +290,7 @@ Repository Node Identity : &lt;153cb870b4665b8c1c348896292b0bad&gt;
Repositories Destination : &lt;0d7334d411d00120cbad24edf355fdd2&gt;
</pre></div>
</div>
<p>If the page server is enabled, the output will also include the Nomad Network destination hash.</p>
<p>If the page node is enabled, the output will also include the Nomad Network destination hash.</p>
<p>You can run <code class="docutils literal notranslate"><span class="pre">rngit</span></code> in service mode with logging to file:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit -s
</pre></div>
@@ -373,7 +373,7 @@ Nomad Network Destination : &lt;50824b711717f97c2fb1166ceddd5ea9&gt;
</pre></div>
</div>
<p><strong>Accessing Repository Pages</strong></p>
<p>Once the page server is running, you can access it from any Nomad Network client by connecting to the Nomad Network destination. The page node provides the following views:</p>
<p>Once the page node is running, you can access it from any Nomad Network client by connecting to the Nomad Network destination. The page node provides the following views:</p>
<ul class="simple">
<li><p><strong>Front Page</strong> - Lists all repository groups accessible to your identity</p></li>
<li><p><strong>Group Page</strong> - Shows all repositories within a group</p></li>
@@ -389,7 +389,7 @@ Nomad Network Destination : &lt;50824b711717f97c2fb1166ceddd5ea9&gt;
</section>
<section id="formatting-syntax-highlighting">
<h2>Formatting &amp; Syntax Highlighting<a class="headerlink" href="#formatting-syntax-highlighting" title="Link to this heading"></a></h2>
<p>If the <code class="docutils literal notranslate"><span class="pre">pygments</span></code> Python module is installed on your system, the page server will automatically apply syntax highlighting to code files. The highlighting supports a wide range of programming languages and uses a color theme optimized for terminal display.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">pygments</span></code> Python module is installed on your system, the page node will automatically apply syntax highlighting to code files. The highlighting supports a wide range of programming languages and uses a color theme optimized for terminal display.</p>
<p>To enable syntax highlighting, install pygments:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install pygments
</pre></div>
@@ -406,7 +406,7 @@ def hello_world():
</section>
<section id="customizing-templates">
<h2>Customizing Templates<a class="headerlink" href="#customizing-templates" title="Link to this heading"></a></h2>
<p>The page server uses a template system that allows complete customization of the generated pages. Templates are stored in the <code class="docutils literal notranslate"><span class="pre">~/.rngit/templates/</span></code> directory as Micron files.</p>
<p>The page node uses a template system that allows complete customization of the generated pages. Templates are stored in the <code class="docutils literal notranslate"><span class="pre">~/.rngit/templates/</span></code> directory as Micron files.</p>
<p>The following template files are supported:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">base.mu</span></code> - Base template wrapping all pages</p></li>
@@ -433,14 +433,14 @@ def hello_world():
<p><strong>Dynamic Templates</strong></p>
<p>Templates can be made executable to generate dynamic content. If a template file has the executable bit set, it will be executed and its stdout used as the template content.</p>
<p><strong>Icon Sets</strong></p>
<p>By default, the page server uses Nerd Font icons. If you prefer simpler icons or your terminal does not support Nerd Fonts, you can enable Unicode icons instead:</p>
<p>By default, the page node uses Nerd Font icons. If you prefer simpler icons or your terminal does not support Nerd Fonts, you can enable Unicode icons instead:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[pages]
serve_nomadnet = yes
unicode_icons = yes
</pre></div>
</div>
<p><strong>Repository Statistics</strong></p>
<p>When statistics recording is enabled (see the <code class="docutils literal notranslate"><span class="pre">record_stats</span></code> configuration option), the page server can display activity charts for each repository. The statistics page shows:</p>
<p>When statistics recording is enabled (see the <code class="docutils literal notranslate"><span class="pre">record_stats</span></code> configuration option), the page node can display activity charts for each repository. The statistics page shows:</p>
<ul class="simple">
<li><p>Total and peak views, fetches and pushes</p></li>
<li><p>Daily activity charts over a 90-day period</p></li>
@@ -448,11 +448,11 @@ unicode_icons = yes
</ul>
<p>To view statistics, a user must have the <code class="docutils literal notranslate"><span class="pre">s</span></code> (stats) permission for the repository. See the Access Configuration section for details on setting permissions.</p>
<p><strong>Repository Thanks</strong></p>
<p>The page server includes a “Thanks” feature that allows users to express appreciation for a repository. On each repository page, a “Thanks” link is displayed showing the current thanks count. Clicking this link registers a thank you for the repository.</p>
<p>The page node includes a “Thanks” feature that allows users to express appreciation for a repository. On each repository page, a “Thanks” link is displayed showing the current thanks count. Clicking this link registers a thank you for the repository.</p>
<p><strong>Configuration Example</strong></p>
<p>A complete page server configuration might look like this:</p>
<p>A complete page node configuration might look like this:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[rngit]
node_name = My Git Server
node_name = My Git Node
announce_interval = 360
record_stats = yes
@@ -476,7 +476,7 @@ unicode_icons = no
<p><strong>The Release Workflow</strong></p>
<p>Creating a release involves specifying a Git tag and a directory containing build artifacts or other files to distribute. The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> client will open your configured <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> to compose release notes, then upload all artifacts to the remote repository node.</p>
<p>To create a release, specify the tag name and path to artifacts:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release create rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo v1.2.0:./dist
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create v1.2.0:./dist
</pre></div>
</div>
<p>This will:</p>
@@ -488,7 +488,7 @@ unicode_icons = no
</ol>
<p>If no <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> environment variable is set, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> will try to use <code class="docutils literal notranslate"><span class="pre">nano</span></code>, <code class="docutils literal notranslate"><span class="pre">vim</span></code> or <code class="docutils literal notranslate"><span class="pre">vi</span></code>. The editor will show a template with instructions. Lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> will be ignored, and if the remaining content is empty after stripping comments, the release creation will be cancelled.</p>
<p><strong>Release Storage &amp; Structure</strong></p>
<p>Releases are stored on the server in a directory named <code class="docutils literal notranslate"><span class="pre">repo_name.releases</span></code> next to the bare repository. Each release is a subdirectory containing:</p>
<p>Releases are stored on the node in a directory named <code class="docutils literal notranslate"><span class="pre">repo_name.releases</span></code> next to the bare repository. Each release is a subdirectory containing:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">META</span></code> - Release metadata in ConfigObj format</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">RELEASE.md</span></code> or <code class="docutils literal notranslate"><span class="pre">RELEASE.mu</span></code> - Release notes</p></li>
@@ -497,7 +497,7 @@ unicode_icons = no
</ul>
<p><strong>Listing Releases</strong></p>
<p>To view all releases for a repository:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release list rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
Tag Status Created Objs Notes
------------------------------------------------------------------
@@ -508,7 +508,7 @@ v1.0.0 published 2024-10-20 16:45 2 Initial release
</div>
<p><strong>Viewing Release Details</strong></p>
<p>To see full information about a specific release:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release view rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo v1.2.0
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view v1.2.0
Release : 0.9.2
Status : published
@@ -529,7 +529,7 @@ Artifacts (4)
</div>
<p><strong>Deleting Releases</strong></p>
<p>To remove a release:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release delete rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo v1.2.0
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete v1.2.0
Are you sure you want to delete release &#39;v1.2.0&#39;? [y/N]: y
Release v1.2.0 deleted
@@ -551,29 +551,158 @@ rel:none # Deny everyone
</pre></div>
</div>
<p><strong>Nomad Network Interface</strong></p>
<p>When the Nomad Network page server is enabled, releases are displayed on a dedicated releases page for each repository. Each release is listed with its tag, creation date, artifact count and a preview of the release notes. Clicking a release shows the full details including formatted release notes and a listing of all artifacts with their sizes.</p>
<p>When the Nomad Network page node is enabled, releases are displayed on a dedicated releases page for each repository. Each release is listed with its tag, creation date, artifact count and a preview of the release notes. Clicking a release shows the full details including formatted release notes and a listing of all artifacts with their sizes.</p>
<p>Only releases with <code class="docutils literal notranslate"><span class="pre">published</span></code> status are visible through the Nomad Network interface. Draft releases (if supported in future implementations) would only be visible through the command-line interface.</p>
<p><strong>All Command-Line Options (rngit release)</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rngit release [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
[-i IDENTITY] [-v] [-q] [--version]
operation repository [target]
[-i PATH] [-v] [-q] [--version]
[repository] [operation] [target]
Reticulum Git Release Manager
positional arguments:
repository URL of remote repository
operation list, view, create or delete
repository URL of remote repository (rns://hash/group/repo)
target tag or tag:path for create, tag for view/delete
target tag and path to release artifacts directory
options:
-h, --help show this help message and exit
--config CONFIG path to alternative config directory
--rnsconfig RNSCONFIG
path to alternative Reticulum config directory
-i IDENTITY, --identity IDENTITY
path to release identity
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-i, --identity PATH path to release identity
-v, --verbose
-q, --quiet
--version show program&#39;s version number and exit
</pre></div>
</div>
</section>
<section id="work-documents">
<h2>Work Documents<a class="headerlink" href="#work-documents" title="Link to this heading"></a></h2>
<p>In addition to releases, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> provides a work document management system for tracking tasks, investigations, issues and progress related to repositories. Work documents are stored as structured msgpack data and support threaded updates and comments.</p>
<p><strong>Listing Work Documents</strong></p>
<p>To view work documents for a repository:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
Active documents
=================
ID Title Author Created Comments
---------------------------------------------------------------------------
1 Implemented new feature 9710b86ba12c4f2e… 2025-01-15 14:32 3
2 Fixed bug in parser 8f3a21c9d84e927b… 2025-01-14 09:15 1
</pre></div>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">--scope</span> <span class="pre">completed</span></code> to view completed work documents, or <code class="docutils literal notranslate"><span class="pre">--scope</span> <span class="pre">all</span></code> to see both active and completed.</p>
<p><strong>Viewing a Work Document</strong></p>
<p>To view a specific work document with all its comments:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view -d 1
Implement new feature (active #1)
=================================
Author : 9710b86ba12c42d1d8f30f74fe509286
Status : active
Created : 2026-05-05 15:11:11
Edited : 2026-05-05 18:22:11
Format : markdown
Updates : 0
This work document tracks the implementation of the new feature...
Updates
=======
#1 by 9710b86ba12c42d1d8f30f74fe509286 at 2026-05-05 15:38:37
-------------------------------------------------------------
Initial analysis complete
</pre></div>
</div>
<p><strong>Creating Work Documents</strong></p>
<p>To create a new work document:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create --title &quot;Investigate performance issue&quot;
</pre></div>
</div>
<p>This will open your configured <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> to compose the document content. Save and exit to create the document, or save an empty document to cancel.</p>
<p><strong>Editing Work Documents</strong></p>
<p>To edit an existing work document:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo edit -d 1
</pre></div>
</div>
<p>This fetches the current content, opens it in your editor, and sends any changes back to the node.</p>
<p><strong>Adding Comments</strong></p>
<p>To add an update to a work document:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo update -d 1
</pre></div>
</div>
<p>This opens your editor to compose the update.</p>
<p><strong>Completing Work Documents</strong></p>
<p>To mark a work document as completed (moving it from <code class="docutils literal notranslate"><span class="pre">active</span></code> to <code class="docutils literal notranslate"><span class="pre">completed</span></code>):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo complete -d 1
Work document #1 completed
</pre></div>
</div>
<p><strong>Activating Work Documents</strong></p>
<p>To mark a work document as active (moving it from <code class="docutils literal notranslate"><span class="pre">completed</span></code> to <code class="docutils literal notranslate"><span class="pre">active</span></code>):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo activate -d 1
Work document #1 activated
</pre></div>
</div>
<p><strong>Deleting Work Documents</strong></p>
<p>To delete a work document and all its comments:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete -id 1
Are you sure you want to delete active work document #1? [y/N]: y
Work document #1 deleted
</pre></div>
</div>
<p><strong>Permissions</strong></p>
<p>Users can view work documents and updates if the have <code class="docutils literal notranslate"><span class="pre">read</span></code> permission for the repository. If users have <code class="docutils literal notranslate"><span class="pre">read</span></code> and <code class="docutils literal notranslate"><span class="pre">interact</span></code>, they can also post updates/comments on existing work documents. Work document management requires having <code class="docutils literal notranslate"><span class="pre">write</span></code> and <code class="docutils literal notranslate"><span class="pre">interact</span></code> permission to the repository. These permissions are configured the same way as any other repository permissions. In the config file or <code class="docutils literal notranslate"><span class="pre">.allowed</span></code> files, use <code class="docutils literal notranslate"><span class="pre">i:target</span></code> to grant work document interaction rights:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># In .allowed file or config
i:all # Allow everyone
i:9710b86... # Allow specific identity
i:none # Deny everyone
</pre></div>
</div>
<p><strong>Author Verification</strong></p>
<p>Users can only edit or delete work documents and updates they created. The author is cryptographically verified from the interacting link’s <code class="docutils literal notranslate"><span class="pre">remote_identity</span></code>.</p>
<p><strong>Storage Format</strong></p>
<p>Work documents are stored in a <code class="docutils literal notranslate"><span class="pre">repo_name.work</span></code> directory next to the repository, containing:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">active/</span></code> - Active work documents</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">completed/</span></code> - Completed work documents</p></li>
</ul>
<p>Each document is a numbered directory containing:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">root</span></code> - The work document content and metadata (msgpack format)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">N</span></code> - Numbered comment files (msgpack format)</p></li>
</ul>
<p><strong>Nomad Network Interface</strong></p>
<p>When the Nomad Network page node is enabled, work documents are viewable through the web interface. The work page lists all documents with their status, and clicking a document shows its full content and updates.</p>
<p><strong>All Command-Line Options (rngit work)</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rngit work [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
[-i PATH] [--scope SCOPE] [-t TITLE] [-d ID] [-v]
[-q] [--version]
[repository] [operation]
Reticulum Git Work Document Manager
positional arguments:
repository URL of remote repository
operation list, view, create, edit, delete, update or complete
options:
-h, --help show this help message and exit
--config CONFIG path to alternative config directory
--rnsconfig RNSCONFIG
path to alternative Reticulum config directory
-i, --identity PATH path to identity
--scope SCOPE document scope: active, completed or all
-t, --title TITLE document title for create
-d, --id ID document ID
-v, --verbose
-q, --quiet
--version show program&#39;s version number and exit
</pre></div>
</div>
@@ -634,13 +763,14 @@ options:
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Using Git Over Reticulum</a><ul>
<li><a class="reference internal" href="#">Git Over Reticulum</a><ul>
<li><a class="reference internal" href="#the-rngit-utility">The rngit Utility</a></li>
<li><a class="reference internal" href="#repository-structure">Repository Structure</a></li>
<li><a class="reference internal" href="#serving-pages-over-nomad-network">Serving Pages Over Nomad Network</a></li>
<li><a class="reference internal" href="#formatting-syntax-highlighting">Formatting &amp; Syntax Highlighting</a></li>
<li><a class="reference internal" href="#customizing-templates">Customizing Templates</a></li>
<li><a class="reference internal" href="#release-management">Release Management</a></li>
<li><a class="reference internal" href="#work-documents">Work Documents</a></li>
</ul>
</li>
</ul>