Other Hosting Options

Products
Support
Company
Free Trial
News
Contact
Buy Now

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Printable Version
Save Permalink URL

Navigation: More Advanced Procedures > Using Version Control Systems > Using Git

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.

Important: Always create "main" as your default repository branch

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.

Admins: Git hosting with BitBucket

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.

Getting your local Help+Manual repository onto BitBucket

The only reliable way to do this is manually via the command line. There are instructions for "migrating repositories to BitBucket" with the SourceTree tool, but they are for the Mac version only and assume the repository is already linked to a remote host like GitHub.

1.First, create an application password for your BitBucket repository, following the instructions here. You MUST copy and store the generated password when it is shown to you. It will never be accessible again.

https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/

2.Initialize your local Help+Manual project as a Git repository. You can do this with GitHub Desktop, as described in GitHub & GitHub Desktop, or via the command line in the project folder:

git init -b main
git add -A
git commit -m "First Commit"

3.Then create an empty repository on BitBucket and get its URL. You can then link and upload the local Help+Manual repository to the BitBucket repository with the following commands. The first time you do this you will be asked for your BitBucket app password:

git remote add source https://username@bitbucket.org/username/reponame.git
git push -u -f https://username@bitbucket.org/username/reponame.git main

Then you're done.

Getting users to download their local working copies

This can be done with GitHub Desktop, but the users will also need a BitBucket account and the BitBucket application password (see above).

1.First, weblink give the user access to the repository on BitBucket.

2.Get the URL of the repository on BitBucket and provide it to the user.

3.User: Open GitHub Desktop and select Clone Repository in the File menu.

BitBucket_Clone

4.Select the URL tab, then paste the BitBucket URL in the central field and choose the local path to an empty folder in the lower field.

5.Click Clone to create the working copy. You will have to enter your BitBucket user name and the application password.

Once this is done, the user can work on the project normally in Help+Manual. It can also be administered with GitHub Desktop, of course.

Admins: Git hosting on your own server

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:

~/git

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

/git

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:

git init -b main
git add -A
git commit -m "First Commit"

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:

git clone --bare .git '../temp/widget_help.git'

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:

scp -r widget_help.git sshuser@domain:~/git

Explanation:

•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.

cd ./git/widget_help.git

git init --bare --shared

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@domain:~/git/widget_help.git .

•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):

git clone sshuser@domain:~/git/widget_help.git .

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.

GitHubD_CloneFromServer

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.

Please enable JavaScript to view this site.

Important: Always create "main" as your default repository branch