Repos¶
The Repos tab (0 in the terminal, Repos in the web UI) reads and
writes git repositories hosted on rngit
nodes over Reticulum: their branches and tags, releases and the files
attached to them, and work documents (issues and proposals) with their
comments. It talks to the node the way the rngit command does, so
repositories, releases and documents made with one show in the other.
rettui can keep a copy of a repository on this computer.
A copy can be sent to another repository.
Committing isn't in rettui: use git with rngit's git-remote-rns helper for that.
rettui can also host repositories for others to read, and mirror,
fork and manage the ones it hosts from this tab: H in the terminal, ⌂ Hosted here in the web UI.
Adding a repository¶
A repository's address is an rns:// URL: the node's address, a group
and the repository, as rns://<node>/<group>/<repo> (the .git at the
end is optional).
nin the list (+ Add in the web UI) adds one by its URL.rns://can be left out.- An
rns://link in a message, a channel or a NomadNet page opens the repository in the Repos tab, as does typing it into the Browser's address bar (g). In the terminal it then asks whether to copy the repository to this computer (typey; it asks only if there is no copy yet). In the web UI, a link in a message or channel has a ⇩ copy link beside it, which asks before it copies. - rngit nodes that announce are listed under the repositories you keep, as
⌂ node and its address, nearest first (in the web UI, under
rngit nodes heard). A node can't list what it hosts, so opening one
(
Enter, or a click in the web UI) shows the node's pages in the Browser; see A node's pages. To add a repository on it, pressnwith the node picked (+ beside it in the web UI): the address starts with the node's. D(× in the web UI) removes a repository from the list (on the node, nothing changes), andycopies its URL.
A node's pages¶
Most rngit nodes serve their pages (the list of what they host, and how to reach it) from a NomadNet identity of their own, so the page isn't at the rngit node's address and opening that does nothing. The first time you open a node, rettui asks which NomadNet node has its pages. It starts with a guess: nodes heard whose name matches the rngit node's (capitals and spaces don't count), nearest first, the best in the box and the rest named in the question. Type or paste the address of the one you want and press Enter. Leaving it empty tries the rngit node itself and forgets any choice.
The choice is kept, so the next time the node opens its pages straight away.
b in the list (⌂ beside the node in the web UI) asks again, to change it.
The rngit node you host knows where its own pages are, so it never asks (see
its pages).
Adding the repositories on a page¶
A node's page usually links to its repositories as rns:// links. a in the
Browser (Keep repos in the web UI) keeps every repository the page links to
in the Repos tab at once, those not kept yet, and says how many were new. It
doesn't copy them to this computer; open one to do that.
Reading a repository¶
Enter opens the picked repository and asks its node for four things,
shown as tabs across the top (← → or Tab switch between them, and
r asks again):
- Branches and tags: every branch and tag, the commit it points at,
and the branch
HEADis on; above them, whether you have a copy and how old it is. - Releases: each release, with its tag, when it was
made, by whom, and how many files it has.
Enteropens one with its notes and files;Enter(org) on a file downloads it. Each file is checked against the release's signed manifest before it's kept: a file that doesn't match, or a manifest not signed by whoever signed the files, is refused and says why. Downloads go in the downloads folder (see Data and Storage) and never replace a file already there. In the web UI, the browser downloads it. - Work: the repository's work documents, in three lists (active,
proposed and completed).
sshows the next list.Enteropens one with its text and comments. A document signed by its author says ✓ signed by them; one whose signature doesn't match its text says ✗ signature doesn't check out. - Permissions: the repository's
.allowedfile, if the node lets you read it (it needsadm).
A node that can't be reached, that refuses, or doesn't have what was asked says so where the list would be.
A copy on this computer¶
m on an open repository (Copy to this computer in the web UI) makes
a copy of it here: every branch and tag the node has, with their history.
It is a bare repository, so it has the history and no working files, and
you can clone from it or read it with git (git clone <folder> work).
Afterwards m (Update the copy) brings the copy up to date, taking
only what's new, and removes the branches and tags the node no longer has,
so the copy matches the node. A repository with a copy is marked ⇩ in
the list, and the Branches and tags pane says what the copy holds and
when it was updated. In the web UI, m does the same.
M (Delete the copy) deletes the copy from this computer, after you
type y; nothing on the node changes. Taking a repository off the list
deletes its copy too.
- The copies are in the
repos/folder of the data folder, by node, group and name (repos/<node>/<group>/<name>.git). rettui picks the folder; neither UI can choose another, and the web UI never reads or writes files elsewhere. - A copy changes nothing outside that folder: rettui reads a repository from a node as data and runs no program from it. A node that sends a branch or tag with a name git wouldn't allow is refused, and nothing of that copy is kept.
- A copy may come to 256 MB. A bigger repository isn't copied, and says so. What a node sends is also checked before it is unpacked: no file in it may come to more than 64 MB, and one step of a copy to more than 1 GB (256 MB on Android), once unpacked (a download of a few hundred bytes can claim gigabytes, and unpacking holds it in memory). A copy over that stops, and says it is too large to copy on this device. A copy may take an hour (or rngit timeout, below, if that's longer), so a big repository over a slow link gets there.
- A copy is fetched a step at a time: the branch HEAD is on, then each other branch (several together if there are many), then the tags. While it goes, the Repos tab says which step it is on and how much of it has come (step 2 of 5, 1.2 of 3.4 MB (35%)), in the web UI too.
- A copy that stops goes on. If the link drops or the node goes quiet
part way, the steps that came are kept, and the message says which step it
stopped at.
magain (Copy to this computer again) fetches only what's missing. A step can't be taken in parts: a single branch with a lot of history starts over if the link drops while it comes. A first copy that stopped before anything came leaves nothing behind. An update that fails keeps what came, so the copy may have some branches newer than others until the next one finishes. - Two copies of one repository at once aren't made; the second is refused.
- Names Windows can't have as a folder (
con,nul, a name ending in a dot) can't be copied. Two repositories whose names differ only in capitals can't both be copied, as they would share a folder on some systems. - Backups don't include
repos/: copy again from the node after a restore.
Reading the copy without the node¶
Enter on a branch or tag in the Branches and tags pane (a click in the web UI)
looks inside the copy: the files at the top, then folders (Enter opens one,
or a file to read its text), Esc or Back one step up, and L (Log)
the newest 200 commits. Nothing is asked of the node, so it works with no
connection. If the node doesn't answer when a repository is opened, its
branches and tags are the copy's, and the pane says so.
- A file is shown as text up to 256 KB, with control characters taken out; a file that isn't text (or isn't valid UTF-8) says so and shows nothing. A file over 8 MB isn't read at all (it would be read whole to show its start), and says how big it is. Symbolic links show as links; the folder of a submodule isn't in the copy.
- Only the copy's own files are read, and a path that tries to leave the repository is refused. The web UI names a repository, a branch or tag and a path inside it, and no folder on this computer.
rngit log DIR REF,rngit tree DIR REF [PATH]andrngit show DIR REF PATHof therngitcommand do the same on a copy's folder.- The copy is as old as its last update (
m): it shows what the node had then. Releases and work documents aren't in a copy and need the node.
Sending a copy to another repository¶
u on an open repository that has a copy (Send to… in the web UI) sends
the copy to another repository, on this node or another: every branch and
tag in it, with their history. It asks for the repository
(rns://<node>/<group>/<repo>), and the repository is made there if the node
hasn't got it (which needs the node's c permission). Then it asks what to do
with a branch the other repository has that differs from the copy:
- add (the default) sends what is new and leaves such branches as they are, and says which they were;
- overwrite replaces them with the copy's;
- same overwrites them too, and also deletes the branches and tags the copy doesn't have, so the other repository ends up the same as the copy.
It needs the other node's write permission for your identity. Only what the other repository lacks is sent, and a second send of an unchanged copy sends nothing. Nothing is changed on the repository the copy is of, and a copy can't be sent to its own repository. The copy being updated is not sent at the same time. The web UI names the two repositories and no folder.
While it goes, the tab says how much of the branch it is sending has gone. If the link drops, the branches already sent stay sent, and sending again sends only the rest, as a second send always sends only what's new.
Writing¶
What the node lets you do depends on its permissions for your identity. A refused change says the node doesn't allow you, and changes nothing.
- Work documents:
wwrites a new one (a title, then its text, in Markdown),pproposes one. On an open document,cadds a comment,echanges its title and text,xmarks it done (or active again), andXdeletes it, after you typey. In the web UI these are buttons, and the text is written in a box of its own. - Releases:
Ppublishes a release of a tag already pushed to the repository: its tag, its notes, then the files to attach (paths on this computer, separated by spaces; put a path with spaces in quotes). In the web UI, the browser picks the files, never files from the computer rettui runs on. Files may come to 32 MB in all.Xon an open release deletes it after you typey; its tag stays in the repository.
Reviewing proposals¶
A document someone proposed sits in the proposed list (s in the Work
pane) until someone who may manage the repository's documents reviews it.
Open it and read it with its comments (c to ask the author something).
a (Accept in the web UI) moves it to the active list; X
(Decline) deletes it, after you type y. If its signature doesn't
prove who wrote it, the document says so, and accepting asks first. The
node decides who may review: without permission, it refuses and nothing
changes.
Who you are to a node¶
rettui asks a node as your rettui identity, so the node's permissions for
you are those of your LXMF identity. If you already use the rngit
command, with access granted to its identity, turn on Use rngit's
identity (Settings, Browsing, rngit_identity) and rettui uses that
identity file instead (~/.rngit/client_identity, or the folder in
$RNGIT_CONFIG). Only the terminal UI can turn it on, since it reads
another program's key.
rngit timeout (rngit_timeout_secs, 120 seconds) is how long a
request may take before it's given up, from 10 seconds to an hour.
Copying a repository and downloading a release file may take an hour
whatever it says, since the whole transfer counts.
Answers are capped so a node can't use up rettui's memory: a file of up to 64 MB, 10,000 branches and tags, and 2,000 entries in a list.