How To Run a Repository

An overview on managing open-source software


Picking your repository host is important. You need something easy when you are new to the world of Git repository management. If you are a little tech-savvy and have an extra server/old computer lying around (with either Linux, or a *BSD derivative available for its hardware), you can use a self-hosted solution like Gitea. Otherwise it is best to either use GitHub or alternatively GitLab. Both being good solutions, and you should look into them each yourself to pick which one.


It is very basic to set up a repository, however, it can be fairly different between platforms. Once set up, you need to remember the URL. We will be using the Keter compiler repository as our example. If you are on Windows 10, there are multiple ways to manage a git repository. If on Gitea or GitLab, there are tools, but it might be best to use the regular git tool found at git-scm.com. If you use GitHub, however, there is a fantastic GUI that makes things a lot easier. The application is called GitHub Desktop. It is also available for MacOS. While on other operating system platforms (i.e. Linux, *BSD, Illumos, OpenIndiana, Haiku, etc), there are other ways to get the same git tool. On these operating systems you can use the terminal to use AND install git. There ARE git GUI tools that are free and available on these platforms, however the tried-and-true method would be to use your system's package manager to install git.


To install git, you either need to install the binaries, or if your system supports one, using the package manager. Here is how to install git using some of the more popular package managers.



You still have a large selection of both paid/free and proprietary/OSS graphical options on almost every OS platform, and of course you can make your own. The official git developer's website has a list of gui clients for git available. Some of the better ones for beginners would be are GitHub Desktop, GitKraken, and ungit. These are our recommendations. Of the three, GitKraken is proprietary, and both ungit and GitHub desktop are licensed under MIT, a very permissive open-source license.


If you decided to use the CLI version of git, there are very few commands you really need to know on a day-to-day basis. However, it works better if you learn all of the other options and commands. You need to know how to run these commands in order, from git clone [url]. That will allow you to clone the data from ANY repository that is public. git add . adds all of the modifications in your project directory to the next commit. git commit -m "[commit message]" is the actual commit, and final change. To upload that change to your git is by running the command git push origin [branch], where branch is usually either "master" or "main". Be sure to look further into these commands.


Now that we over-explained the basics to git, let's talk about actual management. When running a new project, you need to do a lot (larger the community, the more difficult to manage). You need to manage pull requests, issues, and documentation as the MINIMUM. A pull request is when someone forks your software to make a change and returns it. Make sure to ALWAYS check and test pull requests. People will also open what are called "issues" where people either find problems, give ideas to enhance software, and to request various changes. Make sure to use tags and labels for issues as much as possible, and make issues you find in that same page. Sometimes there are problems with these ideas. You don't have to accept all pull requests and to fix all issues. Sometimes, it is best to follow your vision.


Documentation is split into two parts. Code comments, and actual documentation. Documentation can be done in the README file - however, it might be best to avoid doing that. Using an external or internal wiki - GitHub, for example, has a built-in wiki tool. Finally, having a website for documentation - Keter does this option. Which one you use depends on what you are doing, and if you are unsure, it doesn't really hurt to have all three. An fairly easy documentation tool is called ReadTheDocs. ReadTheDocs is a free (for open-source software) tool to host a website with documentation.


By no means is this a complete tutorial. This is just some information to help you get started making open-source software. Learning is best done by just jumping in slowly, and researching for yourself. This overview was mostly to give you a couple of resources to get you started.