Almost everything on Forgejo happens in a repository. Think of a repository as a home for your project, where all of its source code can be organized using Git, as well as where you can track issues and read and write wikis.
This article will guide you through creating your first repository on Forgejo, connecting your local development environment and making your first commit.
- **Owner** Here, you can specify whether you want this to be your own personal project or whether you want it to be part of an organization that you're a part of
- **Repository name** A name for your repository (which will also be part of its path, in this case `https://codeberg.org/knut/foobar`)
- **Visibility** Repositories are either _public_ or _private_, where public means that everyone will be able to access your repository, while your private repositories can only be accessed by you and your collaborators (see [Invite Collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/))
- **Description** A short description that appears next to your repository's name where appropriate
- **Template** Occasionally you may want to generate your repository from an existing template. In that case, you can specify that template here. Otherwise, simply leave this field empty.
- **Issue Labels** If you want to initialize your project's issue tracker with a set of labels that you can use to categorize issues, you can choose one here. You don't have to choose this right away though, as you can choose and modify issue labels at a later time as well.
- **.gitignore** A [.gitignore](https://git-scm.com/docs/gitignore) file defines which files Git should not keep track of. This is useful, for example to prevent configuration files or binaries to be tracked in version control. You can choose to add a predefined file matching the programming language you use now, or add one manually later.
- **License** Here, you can choose from a list of FSF/OSI approved licenses. A `LICENSE` file will then be added to the repository. For some help on choosing the correct license, have a look at our [licensing article](https://docs.codeberg.org/getting-started/licensing/).
- **README** is the first file one should read when accessing a repository. It's also the first file displayed when accessing a repository, a bit like the "homepage" of your repository. On Forgejo, this is interpreted as a [Markdown](https://docs.codeberg.org/markdown/) file.
- **Initialize repository** In order to add the `LICENSE`, `README` and `.gitignore` files mentioned above to your new repository, make sure you tick this box.
- **Default branch** Using this field, you can choose how to name the default branch of your Git repository. We recommend you use the predefined default.
- **Object format** is the repository's object format. We recommend SHA1 as it's the most compatible. It cannot be changed later once the repository has been created.
You should now see a screen similar to the one below. If you haven't chosen to generate `LICENSE`, `README` and `.gitignore` the screen might show instructions instead, which will vanish after [your first commit](#making-your-first-commit).
- **Repository Settings (1)** is where you can make adjustments to your repository settings, such as setting a project website, changing the repository description, enabling/disabling a wiki and issue tracker or deleting the repository. You may want to give this page a visit right now, to get an overview of your options.
- **The RSS, Watch, Star and Fork buttons (2)** allow you to interact with other people's repositories. While they don't do much for your own repository, when visiting another user's repository, you can click on "Watch" to get notified about everything important happening in that repository, "Star" to show the user your appreciation (and to help other users find interesting projects more quickly) and "Fork" to create your own copy of the repository, for example to make modifications that you want to share with the original author. You can also use the RSS button to get the RSS feed of the repository.
- **The Repository Tabs (3)** contain links to every important feature within this repository (some may not be visible by default):
- **Code** lets you browse through all versions of this repository's code.
- **Issues** is a very important communication tool between the author, their users and their contributors. Think of it as part bug-tracker, part forum.
- **Pull Requests** is where other users can ask the author to "pull" in code, from a fork into the author's program.
- **Releases** is a space where the author can upload finished versions of their program, e.g. binaries
- **Wiki** is a basic wiki feature built into Forgejo.
- **Activity** calculates statistics about this repository.
- **Repository's Git URLs (4)** - use these to let Git know where to find this repository. Don't worry if you don't understand this now - we will look at this in the following section.
In this guide, we'll focus on connecting to Forgejo via HTTP using Git on the command line, but note that there are multiple other ways to connect to Forgejo, as laid out in more detail in the articles:
If you want to start a fresh project (so if you don't already have source code that you want to upload to Forgejo), the quickest way to get started is to clone your newly created repository like this:
> In this example, we'll specify Forgejo as the `origin` remote. You can name your remote any other way, especially if you already have an `origin`, but `origin` is the recommended name for the main remote repository.
When you clone a repository from the Internet, the URL that you got your copy of the repository from will be automatically used for the `origin` remote.
If your local copy of the repository is missing some commits that exist in the remote repository, pushing will result in an error. There are two ways to fix this:
- Run `git pull` to combine your local changes with the changes that exist in the remote repository. If this does not work, please follow the instructions in your terminal.
Now that you've connected your repository to your local development copy, it's time to make your first commit.
> If you didn't generate the `LICENSE` and `README.md` files when creating the repository, it's a good idea to add them now. Just put them in your local development copy's directory and add them to your commit, as shown below.
> If you didn't generate `README.md`, these commands will still work fine. However, instead of "Hello World!" being at the end of the file, it'll be the only line in the file.
> If you want to add all modified files in your source tree, you can run `git add .` but **be careful** as this might add unwanted files as well, so it's a good idea to double-check by running `git status` before committing.
By committing your changes, you create a new step in the version history of your program. They act like snapshots of your program's state at a given point of time, and you will later be able to jump back and forth between them.
> It is recommended to keep commits small and focused, so that, if necessary, they can be reverted or easily adapted into another context without too many side-effects.
To commit your changes, run `git commit` and specify a commit message; this will later help you (and others) to identify that commit when looking back at your version history.
Branch 'main' set up to track remote branch 'main' from 'origin'.
```
The `-u` option sets the upstream remote, which we want to be Codeberg.org, as configured previously.
The `main` argument sets the name of the branch onto which shall be pushed upstream. For this example, it should be the same branch name that you specified when creating the repository.
When connecting via HTTPS, Git will ask you for your username and password, which you can enter interactively.
After refreshing the repository page, you should now see something similar to this:
