forked from cmccabe/rtc-man-pages
parent
432704f801
commit
46fc66be70
@ -0,0 +1,138 @@
|
||||
.\" Manpage for gitbbs
|
||||
.\" Contact me@wangofett.com, wangofett@rawtext.club, or cmccabe@rawtext.club
|
||||
.TH man 5 "26 April 2020" "0.1.0" "gitbbs man page"
|
||||
.SH NAME
|
||||
gitbbs \- rawtext's bulletin board system
|
||||
.SH SYNOPSIS
|
||||
quickstart: git clone ~cmccabe/.gitbbs
|
||||
.SH DESCRIPTION
|
||||
Here on rawtext.club we really like raw text. It's natural that our bulletin board would be built on some raw text conventions as well. One of the very best ways to
|
||||
.I share
|
||||
text in a collaborative fashion is with git. So we decided that we would build our BBS with git! If you're not familiar with git, it's a distributed version control system. That means that rather than one centralized bulletin board, our bulletin board is decentralized. You have to get your copy from another user.
|
||||
|
||||
.SS GIT SETUP
|
||||
The best way to get started is to just clone the git repository. If you've never used git, see
|
||||
.BR git (1)
|
||||
for more information, in particular the
|
||||
.I user.name
|
||||
section in
|
||||
.BR git-config (1).
|
||||
|
||||
If you just want to get started, you can run the following command:
|
||||
|
||||
.RS
|
||||
git config --global user.name
|
||||
.I \(dqYour Name\(dq
|
||||
.sp 0
|
||||
git config --global user.email
|
||||
.I you@yourdomain.example.com
|
||||
.RE
|
||||
|
||||
The easiest values to plug in for email is
|
||||
.I yournick@rawtext.club
|
||||
if you don't have one you'd rather use.
|
||||
|
||||
.SS GET GITBBS
|
||||
Now that you have git configured, it's time to get a copy of the BBS. As mentioned in the SYNOPSIS, probably the best person to get the first copy of the BBS from is the maintainer of RTC, cmccabe. Run the following command
|
||||
|
||||
.RS
|
||||
git clone ~cmccabe/.gitbbs ~/.gitbbs
|
||||
.RE
|
||||
|
||||
By convention, each users' copy is stored in `.gitbbs`. Now you can `cd ~/.gitbbs` and start using your favorite text editor to read and add posts.
|
||||
|
||||
.SH TOPICS/SUBFORUMS IN GITBBS
|
||||
|
||||
Topics/forums as found in a typical BBS are literally just directories. Some topics you're likely to see:
|
||||
|
||||
.SS meta
|
||||
|
||||
That's so meta. Discussion here is for discussing gitbbs itself.
|
||||
|
||||
.SS tech
|
||||
|
||||
These are technology posts. There may end out subposts in here.
|
||||
|
||||
.SS sandbox
|
||||
|
||||
"An it harm none do what ye will" - Doreen Valiente
|
||||
|
||||
In this folder, anything goes. Nothing in this folder is expected to adhere to any format or even continue living from revision to revision. So if you want to experiment with building tools, or mucking around with things in gitbbs, do it here in the sandbox before you inflict it on the rest of the club.
|
||||
|
||||
.SH FILE FORMATS
|
||||
|
||||
Post syntax is inspired by RFC-822.
|
||||
|
||||
Files are named
|
||||
.I YYYY-MM-DD-HH:MM:SS-subject-goes-here.txt
|
||||
|
||||
The file format is pretty simple:
|
||||
|
||||
.RS
|
||||
From:
|
||||
.I Post Author
|
||||
.sp 0
|
||||
Date:
|
||||
.I YYYY-MM-DD HH:MM(:SS)
|
||||
.sp 0
|
||||
Subject:
|
||||
.I subject goes here
|
||||
.RE
|
||||
|
||||
Replies are separated from the main post with `---`, and include the `From` and `Date` headers.
|
||||
|
||||
Once you've replied to any interesting posts and created any that you want, you'll run the following commands:
|
||||
|
||||
.RS
|
||||
git status # Shows what files have changed
|
||||
.sp 0
|
||||
git add
|
||||
.I file1 file2 file3 # Whatever files you've changed
|
||||
.sp 0
|
||||
git commit -m
|
||||
.I 'my updates' # feel free to use a different message
|
||||
.RE
|
||||
|
||||
Now that your post has been made, just wait for someone to pick up your changes, or let them know that you are now part of of gitbbs! Another thing that you can do is to run
|
||||
|
||||
.RS
|
||||
~/.gitbbs/_util/update_remotes.py
|
||||
.RE
|
||||
|
||||
Which will try everyone on RTC to see if they are on gitbbs. Running
|
||||
|
||||
.RS
|
||||
git fetch --all
|
||||
.sp 0
|
||||
~/.gitbbs/_util/get-updates.py
|
||||
.RE
|
||||
|
||||
will pull and merge in everyone's updates after that.
|
||||
|
||||
Happy posting!
|
||||
|
||||
|
||||
.SH BUGS
|
||||
It's possible that your ~/.gitbbs/.git folder (or subfolders) are not world-readable. This will prevent RTC friends from correctly accessing your posts.
|
||||
|
||||
You should be able to avoid this by adding the following to ~/.gitbbs/.git/hooks/post-merge and ~/.gitbbs/.git/hooks/post-commit
|
||||
|
||||
.RS
|
||||
#!/bin/sh
|
||||
.sp 0
|
||||
chmod -R o+Xr ~/.gitbbs
|
||||
.RE
|
||||
|
||||
And then running
|
||||
|
||||
.RS
|
||||
chmod +x ~/.gitbbs/.git/hooks/post-receive
|
||||
.sp 0
|
||||
chmod +x ~/.gitbbs/.git/hooks/post-merge
|
||||
.RE
|
||||
|
||||
.SH AUTHOR
|
||||
Wango Fett (wangofett@rawtext.club or me@wangofett.com)
|
||||
.SH SEE ALSO
|
||||
For more information on git, see
|
||||
.BR git (1).
|
||||
Loading…
Reference in new issue