Move documentation from Wiki to main repo

Clone-%26-commit-via-HTTP-%28username-%26-password%29.md

@@ -0,0 +1,43 @@
+# Clone & commit via HTTP (username & password)
+The user in this examples is `JohnDoe` and it's repository is `foobar`. The repository was created via the Codeberg.org website including a `README.md` file.
+
+```bash
+~$ git clone https://codeberg.org/JohnDoe/foobar.git
+Cloning into 'foobar'...
+remote: Enumerating objects: 3, done.
+remote: Counting objects: 100% (3/3), done.
+remote: Compressing objects: 100% (2/2), done.
+remote: Total 3 (delta 0), reused 0 (delta 0)
+Unpacking objects: 100% (3/3), done.
+```
+
+Modify an existing file
+
+```bash
+~$ cd foobar
+~/foobar$ vim README.md
+```
+
+Commit changes to local repository.
+
+```bash
+~/foobar$ git commit -am 'test'
+[master 10074d7] test
+ 1 file changed, 2 insertions(+), 1 deletion(-)
+```
+
+Synchronize ("push") the modifications from the local repository to the remote one on Codeberg.
+
+```bash
+~/foobar$ git push https://codeberg.org/JohnDoe/foobar.git
+Username for 'https://codeberg.org': JohnDoe
+Password for 'https://JohnDoe@codeberg.org': 
+Counting objects: 3, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (2/2), done.
+Writing objects: 100% (3/3), 266 bytes | 0 bytes/s, done.
+Total 3 (delta 1), reused 0 (delta 0)
+To https://codeberg.org/JohnDoe/foobar.git
+   662e04e..10074d7  master -> master
+```
+

Clone-%26-commit-via-SSH.md

@@ -0,0 +1,42 @@
+# Clone
+The user in this examples is `JohnDoe` and it's repository is `foobar`. The repository was [created](https://codeberg.org/Codeberg/Documentation/wiki/Create-repository---Local-and-on-Codeberg) via the Codeberg.org website including a `README.md` file.
+
+```bash
+~$ git clone git@codeberg.org:JohnDoe/foobar.git
+Cloning into 'foobar'...
+remote: Enumerating objects: 3, done.
+remote: Counting objects: 100% (3/3), done.
+remote: Compressing objects: 100% (2/2), done.
+remote: Total 3 (delta 0), reused 0 (delta 0)
+Unpacking objects: 100% (3/3), done.
+```
+
+# Modify and commit to local repository
+Modify an existing file
+
+```bash
+~$ cd foobar
+~/foobar$ vim README.md
+```
+
+Commit changes to local repository.
+
+```bash
+~/foobar$ git commit -am 'test'
+[master 10074d7] test
+ 1 file changed, 2 insertions(+), 1 deletion(-)
+```
+
+# Synchronize your local repository with the remote one
+```bash
+~/foobar$ git push
+Username for 'https://codeberg.org': JohnDoe
+Password for 'https://JohnDoe@codeberg.org': 
+Counting objects: 3, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (2/2), done.
+Writing objects: 100% (3/3), 266 bytes | 0 bytes/s, done.
+Total 3 (delta 1), reused 0 (delta 0)
+To https://codeberg.org/JohnDoe/foobar.git
+   662e04e..10074d7  master -> master
+```

Create-repository.md

@@ -0,0 +1,36 @@
+# Create a Codeberg repository
+To create a new repository you need to login into your account on Codeberg.org.
+
+After login you can use one of the two buttons shown in the two following pictures.
+
+![Create repository 01](create_repo_01.png "Create repository 01")
+
+![Create repository 02](create_repo_02.png "Create repository 02")
+
+Note it is not possible to use your git on your local machine to push a fresh repository on Codeberg.
+# Connect a local repository to Codeberg
+Keep in mind that you first need to create a repository on Codeberg as stated in the section before.
+
+## Optional: Create the local repository
+If you don't have an existing git repository on your local machine that you can create one.
+```
+mkdir ~/playground
+cd ~/playground
+touch README.md
+git init
+git add README.md
+git commit -m "first commit"
+```
+## Declare Codeberg repository as 'origin'
+Your local repository need to know where the remote one is. It is usual and common to name it `origin`. The string `origin` could be desribed as an alias for the remote repository  on the Codeberg server.
+
+Now you have two protocol variantes to connect: SSH and HTTPS.
+
+**Variant - SSH**
+```
+$ git remote add origin ssh://git@codeberg.org/JohnDoe/playground.git
+```
+**Variant - HTTPS**
+```
+$ git remote add origin https://codeberg.org/JohnDoe/playground.git
+```

Including-images-in-wiki-pages.md

@@ -0,0 +1,26 @@
+### Upload images via git
+
+Currently, gitea supports only images in the base directory of the wiki git. (Gitea wiki pages are stored in a separate wiki right beside the project, wiki pages themselves are markdown files).
+
+A feasible workflow might look like this (replace `<user>` and `<project>` with your user and project name):
+
+```shell
+git clone git@codeberg.org:<user>/<project>.wiki.git
+cd <project>.wiki.git
+## now copy image file into this folder
+git add <codeberg.png>
+git commit -m "add image"
+git push
+```
+
+Now, you can reference the image in markdown, like this:
+
+```markdown
+![image alt text](codeberg.png "image title")
+```
+
+After saving your changes, the image should be visible like this:
+
+*NOTE: In contrast to embedding external images, images in git are only rendered after saving the wiki or markdown file changes.*
+
+![image alt text](codeberg.png "image title")

Merge-multiple-commits-into-one.md

@@ -0,0 +1,49 @@
+Sometimes you will merge multiple commits into one. Maybe the commits are "dirty" full with not working code or embarrasing commit messages. This solution is only one of mutliple possible solutions. See this [stackoverflow question](https://stackoverflow.com/q/2563632/4865723) for more details and variants.
+
+Here is an example.
+
+```
+$ git log --graph --decorate --oneline
+* cf634bb (HEAD -> master) english
+* 722a9c7 zwei
+* e59e6d0 eins
+* c6990ba a
+* 6dfc50b (origin/master, origin/HEAD) ix
+* 10074d7 (tag: test) test
+* 662e04e Initial commit
+
+$ git status
+Auf Branch master
+Ihr Branch ist 4 Commits vor 'origin/master'.
+  (benutzen Sie "git push", um lokale Commits zu publizieren)
+
+nichts zu committen, Arbeitsverzeichnis unverändert
+```
+
+You want to merge the last 4 commits from `a` to `english`.
+
+```
+$ git reset --soft "HEAD~4"
+$ git status
+Auf Branch master
+Ihr Branch ist auf demselben Stand wie 'origin/master'.
+
+Zum Commit vorgemerkte Änderungen:
+  (benutzen Sie "git reset HEAD <Datei>..." zum Entfernen aus der Staging-Area)
+
+	neue Datei:     a
+
+$ git commit --amend
+[master 24e0e06] English
+ Date: Wed May 27 13:56:28 2020 +0200
+ 2 files changed, 3 insertions(+), 1 deletion(-)
+ create mode 100644 a
+
+$ git log --graph --decorate --oneline
+* 24e0e06 (HEAD -> master) English
+* 10074d7 (tag: test) test
+* 662e04e Initial commit
+
+```
+
+After that you can push it to remote repository via `git push`.

Overview.md

@@ -0,0 +1,22 @@
+# Basic topics
+## Start with Codeberg...
+[Create a repository](https://codeberg.org/Codeberg/Documentation/wiki/Create-repository)
+
+[SSH key for Codeberg](https://codeberg.org/Codeberg/Documentation/wiki/SSH-key-for-Codeberg)
+
+## Work with Codeberg...
+[Clone & commit via HTTP (username & password)](https://codeberg.org/Codeberg/Documentation/wiki/Clone-%26-commit-via-HTTP-%28username-%26-password%29)
+
+[Clone & commit via SSH (key file)](https://codeberg.org/Codeberg/Documentation/wiki/Clone-%26-commit-via-SSH)
+
+# Advanced topics
+[Pull requests and GIT flow](https://codeberg.org/Codeberg/Documentation/wiki/Pull-requests-and-GIT-flow)
+
+[Merge multiple commits into one](https://codeberg.org/Codeberg/Documentation/wiki/Merge-multiple-commits-into-one)
+# Wiki related topics
+[Including images in wiki pages](https://codeberg.org/Codeberg/Documentation/wiki/Including-images-in-wiki-pages)
+
+# Other Codeberg related topics
+[Terms of use](https://codeberg.org/codeberg/org/src/branch/master/TermsOfUse.md)
+
+[All Codeberg Wiki Pages](https://codeberg.org/Codeberg/Documentation/wiki/_pages)

Pull-requests-and-GIT-flow.md

@@ -0,0 +1,65 @@
+## Benefits of a pull-request based workflow
+
+> ***&TLDR;*** *Keep an eye on your repository and org permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners need full access to the repo to merge them.*
+
+Although it is perfectly possible to use a GIT project on Codeberg just as single shared central repository for individuals and teams, a collaborative workflow based on pull requests provides many benefits:
+
+- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests. Contributors can easily work on forked repositories.
+- Each pull request collects the full edit history for a fix or feature branch. Contributors can squash this, or keep it, just as they prefer.
+
+### Cheat sheet
+
+Let's say, you would like to contribute to project [https://codeberg.org/Codeberg/build-deploy-gitea](Codeberg/build-deploy-gitea).
+
+First, fork the project you would like to work on, by clicking the `fork` button on the top-right corner of the project page:
+
+![Fork a project](Codeberg-build-deploy-gitea-fork.png)
+
+Then clone it onto your local machine. We assume that you have set up your SSH keys as described in [SSH-key-for-Codeberg](https://codeberg.org/Codeberg/Documentation/wiki/SSH-key-for-Codeberg). This has to be done only once:
+
+```shell
+git clone git@codeberg.org:<YOURCODEBERGUSERNAME>/build-deploy-gitea.git
+```
+
+Now, let's create a feature branch, do some changes, commit, push, edit, commit, push, ..., edit, commit, push:
+
+```shell
+git checkout -b my_cool_feature_branch
+## do some changes
+git commit -m "first feature"
+git push                        ## here you get asked to set your upstream URL, just confirm
+## do more work, edit...
+git add new_file.png
+git commit -m "second feature introducing a new file"
+git push
+## ...
+git commit -m "more work, tidy-up"
+git push
+```
+
+Now you can create the pull request by selecting your feature branch, and clicking on the pull request button:
+
+![Create a pull request](Codeberg-build-deploy-gitea-pull-request.png)
+
+### Keep it up-to-date: rebase pull requests to upstream
+
+Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
+
+In order to track the `upstream` repository, we add a second remote that is pointing to the original project. This has to be done only once:
+
+```shell
+git remote add upstream git@codeberg.org:Codeberg/build-deploy-gitea.git
+```
+
+Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository:
+
+```shell
+git pull --rebase upstream master
+git pull
+```
+
+That's it. You can now push your changes, and create the pull request as usual by clicking on the "pull request" button.
+
+## A friendly note on owner rights, and forced push permissions
+
+Please keep in mind that project owners can do *everything*, including editing and rewriting the history using `force-push`. In some cases this is a useful feature (for example to undo accidental commits that, say, leaked credentials), but in most cases a transparent history based on a pull-request based workflow is surely preferable.

README.md

@@ -1,2 +1,2 @@
 
-#### Please have a look into and consider to help writing the [Documentation Wiki](https://codeberg.org/Codeberg/Documentation/wiki/Overview). This is still very much work-in-progress, the more useful material we collect, the better we can later present it! All contributions very welcome!
+#### Please have a look into and consider to help writing the Documentation Wiki. This is still very much work-in-progress, the more useful material we collect, the better we can later present it! All contributions very welcome!

SSH-key-for-Codeberg.md

@@ -0,0 +1,82 @@
+# Introduction
+It is recommanded to use one key per client. It means if you access your Codeberg repository from your home PC, your laptop and your office PC you should generate spearate keys for each machine.
+
+In the context of Codeberg you should decide yourself if you add a pasphrase to your SSH key or not. Read the on-going discussion about that topic in this [Codeberg-Issue](https://codeberg.org/Codeberg/Documentation/issues/2).
+
+## Table of content
+1. [Generating a SSH key (pair)](#generating-a-ssh-key-pair)
+2. [Add the SSH key to Codeberg](#add-the-ssh-key-to-codeberg)
+3. [Test the SSH connection](#test-the-ssh-connection)
+4. [Avoid re-typing the passphrase](#avoid-re-typing-the-passphrase)
+
+
+# Generating a SSH key (pair)
+
+1. Open a shell (e.g. `git-bash` on Windows or `bash` on Linux).
+
+2. Paste the text below, substituting in your Codeberg email address.
+
+    ```shell
+    $ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+    ```
+
+    This creates a new ssh key, using the provided email as a label:
+
+    ```shell
+    > Generating public/private rsa key pair.
+    ```
+
+3. When you're prompted to "Enter a file in which to save the key," press <kbd>Enter</kbd>. This accepts the default file location:
+
+    ```shell
+    > Enter a file in which to save the key (/c/Users/you/.ssh/id_rsa):[Press enter]
+    ```
+
+4. Enter a passphrase if you want. *See further [discussions](https://codeberg.org/Codeberg/Documentation/issues/2) about the necessity of a passphrase in the context of Codeberg.*
+
+# Add the SSH key to Codeberg
+1. Copy the SSH key to your clipboard. Attention: Copy only the public part of the key not the private one. You can identify it by the `.pub` extension. By default you can find the public key in `$HOME/.ssh/id_rsa.pub`.
+
+    On Linux you can use the `xclip` command like this
+    ```shell
+    $ xclip -sel clip < ~/.ssh/id_rsa.pub
+    ```
+    
+    On Windows use a text editor (e.g. Notepad) or `clip` on the commandline
+    ```shell
+    $ type .ssh/id_rsa.pub | clip
+    ```
+2. Go to the settings section __SSH / GPG Keys__ and click on __Add key__.
+
+    ![screenshot](add_ssh_key.png)
+ 
+3. Give an appropriate name for the key.
+4. Paste your key string from the clipboard into __content__ field.
+
+# Test the SSH connection
+Do this simple test:
+
+```shell
+$ ssh -T git@codeberg.org
+```
+
+The output should look like this:
+
+```shell
+Hi there, You've successfully authenticated, but Gitea does not provide shell access.
+If this is unexpected, please log in with password and setup Gitea under another user.
+```
+    
+*Note: All codeberg users share a single unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access.*
+
+# Avoid re-typing the passphrase
+
+Assuming you created a secure key with passphrase, SSH will prompt you for your passphrase for every connection. Common desktop environments like OSX or Gnome will offer you to cache your passphrase via an SSH agent.
+
+If you are working at the command line, you can alternatively do this directly:
+
+```shell
+$ eval `ssh-agent`
+$ ssh-add
+## enter your passphrase once, this is then cached.
+```