|Scroll Prev Top Next More|
There are many other Git hosting solutions available, but none of them are as user-friendly as GitHub, mainly because most of them are focused on programmers. In addition to this, you can also easily host your Git repositories on your own Internet server, because no server-side software is required. Even so, this does require a fair amount of command line configuration.
This topic provides details on setting up your own Git server for administrators who want to do this. It also includes details on BitBucket as an alternative to GitHub as an example of what less user-friendly hosting solutions can be like.
No matter what method you use for setting up and managing your Git repositories, it is important that you always configure them to use "main" as their default branch. All the Help+Manual Git scripts use this branch and they will fail if you use the older "master" branch instead.
BitBucket is also an excellent and reliable free Git hosting service. Unfortunately, it is also less user-friendly than GitHub for non-programmers. The most critical problem for Help+Manual users is that you can't use GitHub Desktop for uploading your local projects to BitBucket, and the SourceTree Git GUI that is linked to BitBucket is not something that we can recommend for technical writers who are not software developers
However, if you are an administrator and need to use BitBucket for some reason, here is a brief summary of what you need to know for using it to host Help+Manual projects.
Important: Git user name and email address
Your Git user name and email address must match your BitBucket credentials.
Git requires no server-side software. All you need to do to have a central repository on your server is initialize a Help+Manual project as a Git repository, save it on your server and provide secure access for your users. If you are familiar with operations like this, this is really the easiest way to get Git set up for your users.
Absolute prerequisite: Key pair SSH access or other transparent access
Help+Manual cannot stop for password entry during synchronization and it would also be infuriating for users. This means that if you are going to host on your own server, the access must be via SSH and you must install public/private SSH key pairs for each user, or another transparent access mechanism. Whatever method you use, users must be able to access the repository folders without stopping for login entry, and SSH key pairs are generally the best and safest method. This is required so that Help+Manual can synchronize to the server folder transparently and silently.
This is not something we can describe here. See this Microsoft article if you need information to get started.
Step 1: Create a directory for your git repositories on your server
Log into your server with SSH (or edit directly on the server) and create a folder in the location where you want to store all your Git repositories. This should also be a location where you are giving your users access with SSH key pairs.
Let's assume that the directory is going to be called git and that it's going to be on the root level. You will need to modify the paths in the examples below if yours is different, of course.
The path to the folder will then be:
if the folder is in the root of the home directory of the account you are logging into (assumed in the examples below) or just
if it is in the actual root of the server.
Step 2: Create a "bare" repository from the Help+Manual project and install it on the server
The server copy does not actually need the Help+Manual project files. It only needs the .git folder from the project folder containing the repository. Then you can store multiple repositories in the same folder on your server. (Remember, every Git user has the entire repository). This is referred to as a "bare" repository.
First you need to initialize the Help+Manual project as a Git repository. Enter the following commands in the Help+Manual project folder in PowerShell or a Command Console:
Next you need to create the bare repository with a name in another folder. Let's assume it's going to be called temp, on the same level as the project folder, and that the project repository is going to be called widget_help. You do this with the following command:
This copies the .git folder from your Help+Manual project folder to the temp folder as a bare repository called widget_help.git.
The bare repository must have a name – i.e not just .git – as well as being bare, so that you can put multiple repositories in the same folder on your server.
Next you need to copy the bare repository to your Git repository folder on your server with SCP. Windows 10 and above now come with SCP built in, so you should be able to do this from the command console. If it doesn't work there, use PowerShell.
Switch to the folder containing the bare copy you made in the last step and enter this command, replacing the file and folder names and your SSH user name and domain with your own values:
•sshuser is your SSH user name
•domain is your server's domain
•~/git is the path to the repository folder on the server from the login location
Finally, log in to the server with SSH and enter the following commands to switch to the repository folder and initialize the repository on the server for shared access. You will need to adjust the path to the one of your own repository folder on the server, of course.
Your server repository is now ready.
Step 2: Enable users to download their local working copies
Once you have given your users SSH access to the repository folder with key pairs they are already authorized for the repository, so you don't need the additional invite step that is necessary for GitHub or BitBucket. You just need to give the user the SSH user name URL they need to clone the repository themselves or do it in GitHub Desktop if they are afraid of the command line.
SSH user name URL for the users
You give each user their SSH user name URL for the repository, which will be:
•sshuser is the user's SSH user name
•domain is your server's domain
•~/git is the path to the repository folder on the server from the user's login location
•The dot ( . ) at the end is important. It prevents an additional sub-folder from being created in the user's folder
Method 1: Command Line
User: Open a command console, switch to the empty folder where you want to install your local working copy of the project and enter the command (remember to include the dot at the end):
Replace sshuser@domain:~/git/widget_help.git with the user name URL provided by your administrator for the repository.
Method 2: GitHub Desktop
1.Open GitHub Desktop and select Clone Repository in the File menu.
2.Select the URL tab, enter your SSH user name URL in the central field and choose your empty folder for your local working copy with the Choose button.
3.Then just click on Clone to clone your local working copy.
Once this is done, you can work on the project normally in Help+Manual.