# Git on dome.circumlunar.space

## Executive summary

Here's the "tl;dr" for those who know Git already
and just want to get the silly thing working:

- connect with `ssh -p 1010 USER@dome.circumlunar.space` for access
  to git shell
- `public_gopher` contains `.git` and boilerplate `gophermap`,
  and is working directory of `~/gopher.git`
- `.ssh` contains `authorized_keys` with public key(s) you submitted
  (add more through git shell)
- `git clone ssh://USER@dome.circumlunar.space:1010/home/USER/gopher.git`
  clones your gopher repo; commit and push for immediate publication
  (don't try to clone the root repo, it won't work well)
- `git clone ssh://USER@dome.circumlunar.space:1010/home/USER/r/REPO.git`
  clones your additional repo `REPO` (set it up through git shell)

*Thanks to e79e for the idea to this summary!*

---

This document shall help sundogs without [Git][1] experience to get the
basics of Git on [dome.circumlunar.space][2], or "dome" for short. It
keeps things simple, and not always completely correct for the sake
of brevity.

It is highly recommended to consult other and more detailed texts
like [ProGIT][3].

The Dome allows users to upload and modify content published through
the Gopher protocol and controlled through Git. It is not intended for
shell access, therefore mastering Git at least at a very basic level is
required for making sensible use of the Dome.

## Short Description of Git

Git might be described as a file system with integrated versioning,
branching and verification. It is a suite of tools (command line, but
graphical interfaces exist as well) which can work on any "working"
directory tree with a `.git` directory at its root.

It makes use of the file system present in the directory structure, but
installs a "shadow" system in `.git` with complete images of snapshots
of the working directory, so-called "commits". These commits as well
as their history (i.e evolution of the working directory) are logged,
and each commit is identified with its hash value, providing a means of
verification of the integrity of the commit.  This means the `.git`
subdirectory will never reduce in size, but Git therefore can detect
any change in the working directory,

## Structure of User Directory on Dome

At installation of a new user account, the following directories are
set up in the user's home directory:

- `public_gopher` containing a `.git` directory and a `gophermap`
- `gopher.git` containing a bare copy of `public_gopher/.git`
- `.ssh` containing `authorized_keys` with the public key(s) for access

In addition, there are some basic configuration files and a symbolic
link `git-shell-commands` to `/var/local/gigof/templates/basics/` with
commands available to `git-shell` which is invoked when the user attempts
interactive login.

(If you requested an empty/bare gopher directory and repository during
submission of account information, `public_gopher` will only contain `.git`
and you will have to first push from an existing repo, before you can
clone as described below. However, the `mango` git-shell command
provides means to change that, if necessary.)

## Connecting to the Dome

Dome's ssh daemon (server) is *listening on port 1010* but not the
standard port 22. Therefore, you have to specify it when connecting, e.g
with `ssh -p 1010 USER@dome.circumlunar.space` on the command line. It
might be useful to add a configuration entry in your local `.ssh/config`
like

	Host dome
	Hostname dome.circumlunar.space
	Port 1010
	User USER

where `USER` has to be replaced by your user name on Dome.

This will allow you to simply type `ssh dome` to connect to the Dome.

### Interactive Access

Users may log in interactively (with ssh, putty and the like) and use
some basic commands specific to the Dome. The help information given at
the beginning should be self-explanatory; it can be displayed at every
`git>` prompt with `help`.

The `read` and `write` commands provide some crude way for interaction
with the system administrator; this is work in progress, and should
not yet be relied on (especially for time-critical communication).
To remove all messages sent to the admin, use the `clear` command.

You may install additional (bare) git repositories with the `repos`
command (and you can also remove them again).
See the section about additional git repos further down,
for guidance about accessing them, their use and limitations.

If your git repos become large, it might be a good idea to run the `tidy`
command. This will search for all `.git` directories and run `git gc`
and `git fsck` in there. The first command does a garbage collection
and will compress objects in the repository, and the second checks
its integrity. (In case you receive any error messages, please contact
the sysadmin!)  You can see how much space is saved by first running
`stat` then `tidy` then again `stat` and compare the size of your home
directory before and after.

The `tidy` command also completely removes `public_gopher` and reinstalls
it from `gopher.git` by freshly cloning. This helps for repairing, e.g
if untracked files are present in `public_gopher` like when you `git rm`
a file from your remote repo and then push the modified repo, but that
file is be recreated automatically on the dome by some other script.

If you want to completely remove all gopher content, and perhaps switch
between a prepopulated gopherhole (and repository) or a bare one (which
is required if you want to upload a fully working repository from
elsewhere), the `mango` command (for "ma-nage go-pherhole") will help.
**Please remember its subcommands will completely remove all content**
in your current gopherhole as well as `gopher.git` repository, therefore
make sure to have it cloned somewhere else if you might need some of the
contents later on! The Dome cannot recover any files for you.

There is an experimental 'schat' command which allows you to interactively
exchange messages with other users on the Dome. This is only local, i.e
not visible/accessible outside of the Dome, at least for the time being.

You may browse gopherspace and the web with a restricted `lynx`
that presents some useful starting points (URLs) at launch.

### Git Access

The main purpose of the Dome is to publish user controlled content via
the Gopher protocol and uploaded through Git. This is implemented with
a so-called `post-update` git-hook (details will be published elsewhere)
resulting in automatic update of `public_gopher` contents whenever the
preinstalled repository `gopher.git` is updated (by `git push` or similar).

The workflow seen from the user's remote system (private computer, shell
account elsewhere) is as follows:

- (once after setting up of the account) local cloning of content with
  `git clone ssh://USER@dome.circumlunar.space:1010/home/USER/gopher.git`
  resulting in local copy `gopher` of the remote repository (or "repo")
  where `USER` should be replaced by the user's account name on Dome
  (for additional git repos, `../USER/r/REPO.git` would be the address)
- `cd gopher`
- if desired, set up local user information (once) with
  `git config --local user.name "whatever name you like"` and
  `git config --local user.email whatever@wherever.com`
- `git pull` to receive and include changes from remote repository
- do work in the repository, also add files at wish
- `git add NEWFILE` to announce adding of a new file `NEWFILE`
- `git rm OLDFILE` to announce removal of an obsolete `OLDFILE`
- `git commit -a -m "commit message"` to commit all changes in already
  known files (and newly added files) to the local copy
  (Feel free to remove or modify the template gophermap!)
- `git push` to upload and publish all local changes
- if no `-m "commit message" is given, the local editor should open during
  committing, to allow edition of a longer commit message

#### Additional Git Repositories

This section describes the setup and use of git repos which can be
managed by the 'repos' git-shell command mentioned above.
They are available in addition to the `gopher.git` repo, are
not related to the gopher content published, and can be used for
version controlling any content conforming to dome's rules.

##### Published/Private Repos

Please note that by default, all of your
*additional repos may be exported to and cloned from the outside*
as `git://dome.circumlunar.space/~USER/REPO.git` where `USER`
is your account name on dome (prepended with a tilde!),
and `REPO` is the name you set with the 'repos' command.
*The git-daemon providing this export is experimental, and you should not
yet rely on its operation.*
Note: Dome does not provide any http(s) access.

If you desire so, you may request the possibility to set repos to
private (not exported/accessible) by contacting the system administrator,
who may activate the corresponding subcommands for the `repos` command.

Public repos are linked on the main gopherhole (under the "Recent updates"
entry which is rebuilt hourly) and can be found by people from outside.

##### How you should access your additional repos

Independent on whether your additional repos are published or private,
you can access them similar to your main gopher repo at slighly different URLs
`ssh://USER@dome.circumlunar.space:1010/home/USER/r/REPO.git` where
`REPO` is the name you set through the 'repos' git-shell command.
Note the `r/` subdirectory required for reliable handling of repo setup,
which however is not necessary when accessing these repos through `git://...`

(Of course you could clone your publicly accessible repos also through
`git clone git://...` as described above. However, this only allows to
clone and pull, not to push anything, and therefore you would need to add
a remote with the `ssh://...` transport before pushing any local commit.)

### Gopher Access

The Dome has a Gophernicus server running on port 70 (gopher standard)
where all user generated content as well as some content controlled by
the sysadmin is published. Please see the available documentation for
gophermaps, to make sure your gophermap is conforming to the specs after
editing.

*For security reasons, no execution of gophermaps or scripts is possible.*

The local gophernicus code has been patched accordingly, to prevent
execution of any external file.
Cloning from `git://dome.circumlunar.space/gophernicus` will give
you the modified sources (currently in the noexec branch).

## Notes

### Privacy

There is none.

Well, there is some, but please assume everything you will put into
your `gopher.git` may be world (=internet) readable. Default permissions
should be set up so that only you (and in and by principle the sysadmin)
can access your git repository, but the master branch of the repository
will be published and accessible on dome.circumlunar.space -- that's
the purpose of this server, after all!

You may hide files or directories in your gopherhole by giving them
unusual names or setting a `-....<tab>filename` entry in the respective
gophermap (see the document about gophermaps at the server's root).
This is unreliable *security by obscurity.*

A safer way is to create a directory with a name that begins with a dot,
e.g `.hidden` , and to put files that should not be published in there.
However, the administration of Ryumin's Dome does not give any warranty
as to whether this works reliably; as always, responsibility is with you.

By request (see above about interactive access), you may get the ability
to set additional git repos to private (not exported), but in general,
all git repos other than `gopher.git` might be accessible from outside,
and the dome's administration does not give any guarantee for anything.
(Verify that any repo set to private indeed is not accessible through
`git://..` before adding sensitive content!)

---

1: http://www.git-scm.com
2: gopher://dome.circumlunar.space
3: https://www.git-scm.com/book

*2019-06-25 // ryumin*