====== Use Synchronet Git Repository ======

Synchronet uses [[dev: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'' method, which resulted in "checking-out" the source files from  [[dev:CVS]] before building them and now you want to get the [[http://cvs.synchro.net/gitpushlog.ssjs|latest updates]] since the switch to [[dev: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'' or ''src/sbbs3/localdefs.mk'') you will want to copy or move those files into the corresponding location in the new ''repo/src/'' sub-directory.
  - Now go through your normal build steps (e.g. running ''make symlinks'') in the ''repo/src/sbbs3'' sub-directory, adding ''RELEASE=1'' or whatever build options you're used to using. Once the build is complete, due to the ''symlinks'' 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 ''[[dir:ctrl]]/[[custom:text.dat]]'' changes (you probably do) or the latest files from ''[[dir:text]]'', ''docs'', ''[[dir:xtrn]]'', ''[[dir:web]]'', or ''webv4'', you will need to either copy those files or symlink them to their equivalent in the ''repo'' sub-directories at this time. **DO NOT** copy or symlink over your other ''[[dir:ctrl]]/*'' files or you will lose important configuration settings. If you have any locally modified files in your ''[[dir:exec]]'' directory, you'll want to move those to your ''[[dir:mods]]'' 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 [[:dir:|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:
  * https://github.com/SynchronetBBS/sbbs
  * https://gitlab.com/SynchronetBBS/sbbs

==== 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 ''[[dir:exec]]'' and ''[[dir: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'' to ''sbbs/exec'' and the same for ''text''.

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 ''[[config:env#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 [[dev:Git]] communication protocol.

Make the following change to your ''sbbs/repo/.git/config'' file:
<file>
[remote "origin"]
        url = git@gitlab.synchro.net:sbbs/sbbs
</file>
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 [[dev: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 use ''git 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 be ''CONFLICT'' 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/[[dir:exec]]'' directory to the build output directories of the ''sbbs/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 your ''sbbs/repo'' to the latest and greatest source, if that's what you're trying to do.
===== See Also =====
  * [[:howto:|howto index]]

{{tag>git}}