foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity

docs: v1.20: sync Codeberg 77bfb6cc15d180d506881e9629e73d1064c11dda

Browse source
This commit is contained in:
Loïc Dachary 2023-07-18 22:41:41 +02:00 committed by Caesar Schinas
parent a6d5b9e8bf
commit cafdb8e16e
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
6 changed files with 41 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
_images/user/repo-permissions/user-settings-privacy-limited.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 50 KiB

2
user/email-settings.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Email Settings'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/email-settings.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/email-settings.md'
---
By default, Forgejo will send notifications to your registered email addresses.

24
user/first-repository.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: Your First Repository
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/first-repository.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/first-repository.md'
---
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.
@ -11,6 +11,8 @@ This article will guide you through creating your first repository on Forgejo, c
## Creating a Repository
> A note to more advanced users: It's currently not possible to use Push-to-Create to push a fresh repository onto Forgejo.
To create a new repository, you need be logged in to your account.
When you're logged in, you can use one of the two buttons shown in the two following screenshots to create a new repository:
@ -73,11 +75,7 @@ If you want to start a fresh project (so if you don't already have source code t
#### 1. Navigate to your local workspace (optional)
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in the following example.
We assume a Linux machine. `mkdir` creates a new directory, `cd` changes into it.
`$` is indicating that the commands are run as a user without admin permissions.
`~/repositories$` is meant to be read as „current working directory is the repositories folder within the home directory”.
The username here is `knut` on a machine with the name of `iceberg`.
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in this example:
```bash
knut@iceberg:~$ mkdir repositories
@ -99,15 +97,11 @@ remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (4/4), 11.94 KiB | 764.00 KiB/s, done.
The exact values for size and download speed might differ on your machine.
```
#### 3. Navigate to the cloned repository
After cloning, the repository should now be in a new directory with the same name as your repository. In this case, it's called `foobar`.
The command `ls` lists all files within the current folder.
```bash
knut@iceberg:~/repositories$ cd foobar
@ -141,6 +135,12 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
If all is done correctly, this command should output nothing.
> **Errors:**
> If you added an already initalized remote repository and try to push, you will get an error, if your local commit history is different from the history of the remote. You have some choices to resolve the conflict:
>
> - Merge your changes with the ones in the remote `git pull`
> - If you are sure, that you want to overwrite all changes in the remote, you can force push with `git -f push`
## Making your first commit
Now that you've connected your repository to your local development copy, it's time to make your first commit.
@ -221,8 +221,6 @@ Date: Sat Sep 26 12:29:57 2020 +0200
Initial commit
```
The dates, commit hash and author will be different for your project.
#### 4. Push your changes to Forgejo
If you're happy with the changes you made, the next step is to present them to the world by pushing them to Forgejo:
@ -244,8 +242,6 @@ To https://codeberg.org/knut/foobar
Branch 'main' set up to track remote branch 'main' from 'origin'.
```
It is expected that you won't see any visual feedback when entering your password. Type it blind and hit return.
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.

2
user/issue-tracking-basics.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'The Basics of Issue Tracking'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/issue-tracking-basics.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/issue-tracking-basics.md'
---
Issues are an important mean of communication on Forgejo.

16
user/repo-permissions.md
View file

@ -2,15 +2,21 @@
layout: '~/layouts/Markdown.astro'
title: 'Repository Permissions'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/collaborating/repo-permissions.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/collaborating/repo-permissions.md'
---
<!-- See also https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/permissions.en-us.md -->
When you invite collaborators to join your repository or when you create teams for your organization, you have to decide what each collaborator/team is allowed to do.
You can assign teams different levels of permission for each unit (e.g. issues, PR's, wiki).
## Profile and Visibility
Visibility of your repositories is in general inherited from your profile. So other user can only see your repositories, if your profile is _public_.
If you want to limit visibility access to your repositories you can set your **user visibility** in the user privacy settings to **Limited**. Even if your repository is public, non-contributors will get a 404-error if they try to access your repository.
![screenshot showing the updated README](../../../../images/v1.20/user/repo-permissions/user-settings-privacy-limited.webp)
## Collaborators
There are four permission levels: Read, Write, Administrator and Owner.
@ -118,7 +124,7 @@ Each unit is configured to have one of these 3 permission levels:
- Read: Members can view the unit, and do standard actions for that unit (See the Read column under [Collaborators](#collaborators)).
- Write: Members can view the unit, and execute write actions that unit (See the Write column under [Collaborators](#collaborators)).
When a team is configured to have administrator access, you cannot change units.
When a team is configured to have administrator access, when this is specified, you cannot change units. The team will have admin permissions (See the Admin column under _Collaborators_).
Currently, there are six units that can be configured:
@ -134,4 +140,4 @@ There are also two units which can be toggled:
- External Wiki: access to external wiki.
- External Issues: access to the external issue tracker.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, they will get administrator access to the repository.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, he/she will get administrator access to the repository.

22
user/wiki.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Integrated Wiki'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/wiki.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/wiki.md'
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
@ -15,7 +15,7 @@ The user in these examples is `knut`, the polar bear and its repository is `foob
To enable the wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even anonymous guests can access the wiki.
> Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
> The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
To edit the wiki `write` permission to the repository is required.
@ -35,7 +35,9 @@ The web UI in your browser is currently limited to adding, updating, and deletin
![Wiki home page with edit buttons](../../../../images/v1.20/user/wiki/wiki_pageview.png)
## Adding content via a local Git client
Clicking on the "Insert Image" button will make the following text appear in your text editor: `![](https://)`
## Adding content using a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo.
@ -48,7 +50,7 @@ git commit -am "create Home page"
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
### Adding images
### Adding images using a local Git client
You can add images to the root directory or a specific subfolder (like `assets` or `images`) using your local Git client.
@ -64,12 +66,24 @@ git commit -m "add image"
git push
```
## Attaching images in Markdown documents
Now, you can reference the image in Markdown, like this:
**File in repository**:
```markdown
![image alt text](images/image.png 'image title')
```
**External image**:
```markdown
![image alt text](https://example.com/image.jpg 'image title')
```
When including images from Forgejo repositories, keep in mind that _you should use the raw version of the image._
After saving your changes, the image should be visible.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.