Table of Contents
Use Synchronet Git Repository
Synchronet uses Git for its Source Repository (as of August, 2020).
Updating an Install from CVS
So you previously installed Synchronet for *nix using the install/GNUmakefile
1) method, which resulted in “checking-out” the source files from CVS before building them and now you want to get the latest updates since the switch to Git.
- Follow the Clone instructions below, cloning into a sub-directory off of your Synchronet install directory (e.g.
/sbbs/repo
). - If you previously had any
localdefs.mk
files (e.g.src/build/localdefs.mk
orsrc/sbbs3/localdefs.mk
) you will want to copy or move those files into the corresponding location in the newrepo/src/
sub-directory. - Now go through your normal build steps (e.g. running
make symlinks
) in therepo/src/sbbs3
sub-directory, addingRELEASE=1
or whatever build options you're used to using. Once the build is complete, due to thesymlinks
target, your executable binary files in/sbbs/exec/
should now be updated with the “latest and greatest” Synchronet development version. - If you want the latest
ctrl/text.dat
changes (you probably do) or the latest files fromtext
,docs
,xtrn
,web
, orwebv4
, you will need to either copy those files or symlink them to their equivalent in therepo
sub-directories at this time. DO NOT copy or symlink over your otherctrl/*
files or you will lose important configuration settings. If you have any locally modified files in yourexec
directory, you'll want to move those to yourmods
directory before overwriting them with upstream files.
Clone
It is highly recommended to clone the Synchronet Git Repository into a directory other than the directory you are/will-be using for your live Synchronet BBS. The following steps clone the repository into the directory /sbbs/repo
, so if your Synchronet directory tree was located at /sbbs
, then the repository would be cloned to a sub-directory (folder) named repo
. This will result in duplicates of several Synchronet directories, e.g.
/sbbs/exec
and/sbbs/repo/exec
/sbbs/ctrl
and/sbbs/repo/ctrl
/sbbs/text
and/sbbs/repo/text
etc., once the BBS is installed, configured, and operational.
To clone the repository to your local system (into a directory named /sbbs/repo
) using unauthenticated HTTPS:
$ git clone https://gitlab.synchro.net/main/sbbs /sbbs/repo
To clone the repository to your local system using SSH (your public key must be configured for your user account at gitlab.synchro.net
):
$ git clone git@gitlab.synchro.net:main/sbbs /sbbs/repo
Mirrors
The Synchronet Source Repository is mirrored (e.g. for faster download/cloning) at:
Branches
The master
branch may occasionally not successfully build for your specific platform. If this happens, checking out the latest successful-nightly-build for your platform should resolve this issue. e.g. for Linux-x64:
$ git checkout dailybuild_linux-x64
If you wish to switch back to the master
branch a later point:
$ git checkout master
Read-only Directories
If you do not plan to make significant changes to the contents of the exec
and text
directories, you can make their later update more seamless (e.g. upon git clone
) by either:
- Setting SCFG->System->Advanced Options->Exec Directory to
../repo/exec/
and Setting SCFG->Nodes->Node 1->Advanced Options->Text Directory to../repo/text
- Or (on *nix-like systems) symlinking
sbbs/repo/exec
tosbbs/exec
and the same fortext
.
This approach is feasible even for sysops that make changes to files in exec
and text
by using a local branch (i.e. merging in upstream changes from the master
branch), but that setup should be pursued only by experienced Git users.
Note:
If you do decide to change your configured exec
directory, be sure to update your SBBSEXEC
environment variable to point to the correct location too.
Create and Checkout a Branch
If you're going to make any changes to any files in the repo, you should first create a local branch. To create a local branch and check it out (make it the current branch):
$ git checkout -b <your-awesome-branch-name>
Merge Upstream Changes into Your Branch
To download the latest changes from the Synchronet repository and integrate (merge) with your changed files, while your branch is checked-out (run git status
if you're unsure):
$ git pull $ git merge origin/master
Push Without Merge Commit
You attempt to push a set of commits and get the following error:
$ git push To gitlab.synchro.net:sbbs/sbbs.git ! [rejected] master -> master (non-fast-forward) error: failed to push some refs to 'git@gitlab.synchro.net:sbbs/sbbs.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
To avoid a 'merge commit'
$ git pull --rebase --autostash
Then push your changes.
'up' alias
To create a convenient alias for the git pull –rebase
usage above:
$ git config --global alias.up "pull --rebase --autostash"
Now you can just run git up
instead of git pull
.
Push Without Password
If you're being prompted for your gitlab password when pushing changes to gitlab.synchro.net
, that's an indicator that you're using https
rather than ssh
(the default) for the Git communication protocol.
Make the following change to your sbbs/repo/.git/config
file:
[remote "origin"] url = git@gitlab.synchro.net:sbbs/sbbs
With that change, if your SSH public key is registered with your gitlab.synchro.net
user account, git
should automatically authenticate for push
requests.
Stash
A git pull
fails with the message:
error: Your local changes to the following files would be overwritten by merge:
Whether you knowingly or intentionally modified any files, or Git just did it automatically (e.g. changing line-endings of text files), the suggested solution is to “Stash Local Changes”:
- Run
git diff -w
in the repo (show changes, ignoring white-space) and confirm that no file differences are shown. If file differences are shown, you can still proceed with these instructions. - Run
git stash
in the repo to push any changed (or presumed changed) files into your local git stash. If you wish, you can usegit stash show
to display what changes are currently stashed. - Run
git pull
in the repo to merge any upstream changes into your local repo. - Run
git stash pop
in the repo to re-apply the changes previously pushed to your local git stash. If there were in fact no local changes, this will actually do nothing but empty the local git stash. If there are “merge conflicts” when the stashed changes are reapplied, there will beCONFLICT
warnings that you will need to address by editing the listed files. - Run
git diff
in the repo (show changes, including white-space) to confirm that either no changes or only your expected changes are shown.
Reset
If you're getting Git errors about local changes to files that you didn't make and you just want to reset every file in the repository to its latest upstream contents, run these commands:
$ cd /path/to/sbbs/repo $ git fetch --all $ git reset --hard origin/master $ git checkout master
After the successful execution of these commands, your sbbs
Git repo should be reset back to the current upstream contents.
Delete the Repo
Under normal circumstances, you should never need to delete your Synchronet source repository (the sbbs/repo
directory) and it is strongly advised that you do not:
- Most installations use symbolic links from the
sbbs/exec
directory to the build output directories of thesbbs/repo
. Deleting the repo would delete your working executable binary files. - The repo is your copy of the working source code. Deleting the repo would delete your copy of your working source code.
- Just
git pull
to update yoursbbs/repo
to the latest and greatest source, if that's what you're trying to do.