aniani/gitea
1
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2024-11-01 08:47:40 -04:00
Code
12a098920c
gitea/docs/content/doc/usage/command-line.en-us.md

284 lines
16 KiB
Markdown
Raw Normal View History

Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
---
date: "2017-01-01T16:00:00+02:00"
title: "Usage: Command Line"
slug: "command-line"
weight: 10
toc: true
draft: false
menu:
sidebar:
parent: "usage"
name: "Command Line"
weight: 10
identifier: "command-line"
---
## Command Line
### Usage
Make CustomPath, CustomConf and AppWorkPath configurable at build (#6631)
2019-04-29 14:08:21 -04:00
`gitea [global options] command [command or global options] [arguments...]`
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
### Global options
Make CustomPath, CustomConf and AppWorkPath configurable at build (#6631)
2019-04-29 14:08:21 -04:00
All global options can be placed at the command level.
- `--help`, `-h`: Show help text and exit. Optional.
- `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`).
Add work path CLI option (#6922) Makes it possible to set the work path as a CLI option instead of relying on environment variables which are somewhat opaque
2019-05-14 11:20:35 -04:00
- `--custom-path path`, `-C path`: Location of the Gitea custom folder. Optional. (default: `AppWorkPath`/custom or `$GITEA_CUSTOM`).
- `--config path`, `-c path`: Gitea configuration file path. Optional. (default: `custom`/conf/app.ini).
- `--work-path path`, `-w path`: Gitea `AppWorkPath`. Optional. (default: LOCATION_OF_GITEA_BINARY or `$GITEA_WORK_DIR`)
NB: The defaults custom-path, config and work-path can also be
changed at build time (if preferred).
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
### Commands
#### web
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
Starts the server:
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Options:
- `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file.
- `--pid path`, `-P path`: Pidfile path. Optional.
- Examples:
- `gitea web`
- `gitea web --port 80`
- `gitea web --config /etc/gitea.ini --pid /var/run/gitea.pid`
- Notes:
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
- Gitea should not be run as root. To bind to a port below 1000, you can use setcap on
Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
redone every time you update Gitea.
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
#### admin
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
Admin operations:
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Commands:
- `create-user`
document command line flags (#5675)
2019-01-09 12:52:10 -05:00
- Options:
Add username flag in create-user command (#6534) * Add username flag in create-user command * Fix the error message * Change name to username on flag of create-user command * Include create-user flags of both versions * delete deprecated example of create-user command
2019-04-09 11:21:55 -04:00
- `--name value`: Username. Required. As of gitea 1.9.0, use the `--username` flag instead.
- `--username value`: Username. Required. New in gitea 1.9.0.
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- `--password value`: Password. Required.
- `--email value`: Email. Required.
- `--admin`: If provided, this makes the user an admin. Optional.
add docs for #6847 (#7132)
2019-06-05 12:24:09 -04:00
- `--access-token`: If provided, an access token will be created for the user. Optional. (default: false).
document command line flags (#5675)
2019-01-09 12:52:10 -05:00
- `--must-change-password`: If provided, the created user will be required to choose a newer password after
update docs (#6032)
2019-02-10 17:10:00 -05:00
the initial login. Optional. (default: true).
document command line flags (#5675)
2019-01-09 12:52:10 -05:00
- ``--random-password``: If provided, a randomly generated password will be used as the password of
the created user. The value of `--password` will be discarded. Optional.
- `--random-password-length`: If provided, it will be used to configure the length of the randomly
generated password. Optional. (default: 12)
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Examples:
Add username flag in create-user command (#6534) * Add username flag in create-user command * Fix the error message * Change name to username on flag of create-user command * Include create-user flags of both versions * delete deprecated example of create-user command
2019-04-09 11:21:55 -04:00
- `gitea admin create-user --username myname --password asecurepassword --email me@example.com`
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- `change-password`
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
- Options:
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- `--username value`, `-u value`: Username. Required.
- `--password value`, `-p value`: New password. Required.
- Examples:
- `gitea admin change-password --username myname --password asecurepassword`
Add cli commands to regen hooks & keys (#3979) * Add cli commands to regen hooks & keys * make fmt * Allow passing path to config as an option * add docs
2018-05-16 21:35:07 -04:00
- `regenerate`
- Options:
- `hooks`: Regenerate git-hooks for all repositories
- `keys`: Regenerate authorized_keys file
- Examples:
- `gitea admin regenerate hooks`
- `gitea admin regenerate keys`
Add/remove/list oauth providers via cli (#4591)
2018-09-12 10:46:02 -04:00
- `auth`:
- `list`:
- Description: lists all external authentication sources that exist
- Examples:
fix typos in docs command-line examples (#6466) Signed-off-by: Ilya Pavlov <ilux@cpan.org>
2019-03-29 08:16:07 -04:00
- `gitea admin auth list`
Add/remove/list oauth providers via cli (#4591)
2018-09-12 10:46:02 -04:00
- `delete`:
- Options:
- `--id`: ID of source to be deleted. Required.
- Examples:
fix typos in docs command-line examples (#6466) Signed-off-by: Ilya Pavlov <ilux@cpan.org>
2019-03-29 08:16:07 -04:00
- `gitea admin auth delete --id 1`
Add/remove/list oauth providers via cli (#4591)
2018-09-12 10:46:02 -04:00
- `add-oauth`:
- Options:
- `--name`: Application Name.
- `--provider`: OAuth2 Provider.
- `--key`: Client ID (Key).
- `--secret`: Client Secret.
- `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url`: Use a custom Email URL (option for GitHub).
- Examples:
fix typos in docs command-line examples (#6466) Signed-off-by: Ilya Pavlov <ilux@cpan.org>
2019-03-29 08:16:07 -04:00
- `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
Add/remove/list oauth providers via cli (#4591)
2018-09-12 10:46:02 -04:00
- `update-oauth`:
- Options:
- `--id`: ID of source to be updated. Required.
- `--name`: Application Name.
- `--provider`: OAuth2 Provider.
- `--key`: Client ID (Key).
- `--secret`: Client Secret.
- `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url`: Use a custom Email URL (option for GitHub).
- Examples:
fix typos in docs command-line examples (#6466) Signed-off-by: Ilya Pavlov <ilux@cpan.org>
2019-03-29 08:16:07 -04:00
- `gitea admin auth update-oauth --id 1 --name external-github-updated`
Add CLI commands to manage LDAP authentication source (#6681) * add CLI commands to manage LDAP authentication source * delete Gogs copyright * remove unused return value of func parseLoginSource * fix comment Co-Authored-By: ngourdon <31291059+ngourdon@users.noreply.github.com> * remove config flag already present in global flags * remove config flag from ldap commands in docs * remove config flag handling
2019-06-17 14:32:20 -04:00
- `add-ldap`: Add new LDAP (via Bind DN) authentication source
- Options:
- `--name value`: Authentication name. Required.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value`: The password for the Bind DN, if any.
- `--attributes-in-bind`: Fetch attributes in bind DN context.
- `--synchronize-users`: Enable user synchronization.
- `--page-size value`: Search page size.
- Examples:
- `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail`
- `update-ldap`: Update existing LDAP (via Bind DN) authentication source
- Options:
- `--id value`: ID of authentication source. Required.
- `--name value`: Authentication name.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached.
- `--port value`: The port to use when connecting to the LDAP server.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value`: The password for the Bind DN, if any.
- `--attributes-in-bind`: Fetch attributes in bind DN context.
- `--synchronize-users`: Enable user synchronization.
- `--page-size value`: Search page size.
- Examples:
- `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
- `add-ldap-simple`: Add new LDAP (simple auth) authentication source
- Options:
- `--name value`: Authentication name. Required.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--user-dn value`: The user’s DN. Required.
- Examples:
- `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
- `update-ldap-simple`: Update existing LDAP (simple auth) authentication source
- Options:
- `--id value`: ID of authentication source. Required.
- `--name value`: Authentication name.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached.
- `--port value`: The port to use when connecting to the LDAP server.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--user-dn value`: The user’s DN.
- Examples:
- `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
#### cert
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
directory and will overwrite any existing files.
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Options:
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
- `--host value`: Comma seperated hostnames and ips which this certificate is valid for.
Wildcards are supported. Required.
- `--ecdsa-curve value`: ECDSA curve to use to generate a key. Optional. Valid options
are P224, P256, P384, P521.
- `--rsa-bits value`: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
set. (default: 2048).
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- `--start-date value`: Creation date. Optional. (format: `Jan 1 15:04:05 2011`).
- `--duration value`: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
- `--ca`: If provided, this cert generates it's own certificate authority. Optional.
- Examples:
- `gitea cert --host git.example.com,example.com,www.example.com --ca`
#### dump
General documentation cleanup (#3317) * Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
2018-01-08 17:48:42 -05:00
Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
in the current directory.
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Options:
support custom file name in `gitea dump` command (#6474) * support custom file name in `gitea dump` command * simpler approach to handle default dump file name in `gitea dump` command
2019-04-01 00:31:37 -04:00
- `--file name`, `-f name`: Name of the dump file with will be created. Optional. (default: gitea-dump-[timestamp].zip).
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- `--tempdir path`, `-t path`: Path to the temporary directory used. Optional. (default: /tmp).
Add flag to skip repository dumping (#5695)
2019-01-13 16:52:26 -05:00
- `--skip-repository`, `-R`: Skip the repository dumping. Optional.
- `--database`, `-d`: Specify the database SQL syntax. Optional.
Change verbose flag in dump command to avoid colliding with global version flag (#6822) * Change verbose flag to avoid colliding with version flag * Update docs Signed-off-by: jolheiser <john.olheiser@gmail.com>
2019-05-01 16:36:09 -04:00
- `--verbose`, `-V`: If provided, shows additional details. Optional.
Import docs into main repository (#2874) * import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2017-11-26 16:44:32 -05:00
- Examples:
- `gitea dump`
- `gitea dump --verbose`
Document generate commands (#3532) * Document generate commands Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv> * Fix examples and grammar Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv>
2018-02-18 22:23:41 -05:00
#### generate
Generates random values and tokens for usage in configuration file. Useful for generating values
for automatic deployments.
- Commands:
- `secret`:
- Options:
- `INTERNAL_TOKEN`: Token used for an internal API call authentication.
Rename LFS_JWT_SECRET to include OAUTH2 as well (#6826)
2019-05-01 22:32:06 -04:00
- `JWT_SECRET`: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility).
Document generate commands (#3532) * Document generate commands Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv> * Fix examples and grammar Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv>
2018-02-18 22:23:41 -05:00
- `SECRET_KEY`: Global secret key.
- Examples:
- `gitea generate secret INTERNAL_TOKEN`
Rename LFS_JWT_SECRET to include OAUTH2 as well (#6826)
2019-05-01 22:32:06 -04:00
- `gitea generate secret JWT_SECRET`
Document generate commands (#3532) * Document generate commands Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv> * Fix examples and grammar Signed-off-by: Lauris Bukšis-Haberkorns <lauris@nix.lv>
2018-02-18 22:23:41 -05:00
- `gitea generate secret SECRET_KEY`
Create AuthorizedKeysCommand (#5236)
2018-11-01 09:41:07 -04:00
#### keys
Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
```ini
...
# The value of -e and the AuthorizedKeysCommandUser should match the
# username running gitea
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
```
The command will return the appropriate authorized_keys line for the
provided key. You should also set the value
`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
`app.ini`.
NB: opensshd requires the gitea program to be owned by root and not
writable by group or others. The program must be specified by an absolute
path.
Copy Permalink