diff --git a/docs/advancing/cli-reference.mdx b/docs/advancing/cli-reference.mdx new file mode 100644 index 000000000..f2a3a1c51 --- /dev/null +++ b/docs/advancing/cli-reference.mdx @@ -0,0 +1,67 @@ +--- +title: "CLI reference" +description: "Discover all the commands available in the gogs binary" +icon: "terminal" +--- + +Most people know `gogs web` for starting the server, but the `gogs` binary ships with several other commands that help you manage your instance from the command line. + +Run `gogs --help` at any time to see the full list of available commands, and `gogs --help` for details on a specific command. + + + Every command accepts a `--config` (`-c`) flag to specify a custom configuration file path. The default is `custom/conf/app.ini`. + + +## Starting the server + +```bash +gogs web +``` + +The `web` command starts the HTTP server that powers the web UI, the REST API, and Git HTTP operations. Use the `--port` (`-p`) flag to override the default listening port. + +## Administration + +```bash +gogs admin +``` + +The `admin` command lets you perform maintenance tasks without going through the web interface. Available subcommands include: + +| Subcommand | Purpose | +|---|---| +| `create-user` | Create a new user account (with optional `--admin` flag). | +| `delete-inactive-users` | Remove user accounts that were never activated. | +| `delete-repository-archives` | Clean up generated repository archive files. | +| `delete-missing-repositories` | Remove database records for repositories whose Git data is missing on disk. | +| `collect-garbage` | Run `git gc` across all repositories. | +| `rewrite-authorized-keys` | Regenerate the SSH `authorized_keys` file from the database. | +| `resync-hooks` | Re-write Git server-side hooks for all repositories. | +| `reinit-missing-repositories` | Re-initialize bare Git repositories that are missing on disk. | + + + `rewrite-authorized-keys` replaces the entire `authorized_keys` file. Any non-Gogs keys in that file will be lost. + + +## Importing data + +```bash +gogs import locale --source --target +``` + +The `import` command helps you bring portable data from other Gogs installations into your local instance. Currently the only subcommand is `locale`, which merges locale files from a source directory into a target directory. + +## Backup and restore + +```bash +gogs backup +gogs restore --from +``` + +`backup` dumps the database, repositories, and related files into a single zip archive. `restore` imports everything back from an archive, which is useful for migrating Gogs to another server or switching database engines. + +Both commands support `--database-only` and `--exclude-repos` flags to narrow the scope. `backup` additionally supports `--exclude-mirror-repos` and `--target` to control where the archive is saved. + +## Internal commands + +The `serv` and `hook` commands are used internally by the SSH and Git subsystems. You generally do not need to invoke them directly, but they are the reason Gogs can handle SSH authentication and server-side Git hooks without any external tooling. diff --git a/docs/asking/faq.mdx b/docs/asking/faq.mdx index e407bc6b0..3b9176e02 100644 --- a/docs/asking/faq.mdx +++ b/docs/asking/faq.mdx @@ -13,7 +13,7 @@ Answers to common questions about Gogs configuration, administration, and usage. You can change the listening port on the first run by passing the `-port` flag: ```bash - ./gogs web -port 3001 + gogs web -port 3001 ``` This flag also updates the port number shown on the install page, so pick the port you intend to keep using. @@ -58,7 +58,7 @@ Answers to common questions about Gogs configuration, administration, and usage. ```bash su git cd /home/git/gogs - ./gogs admin create-user --name tmpuser --password tmppassword --admin --email tmp@example.com + gogs admin create-user --name tmpuser --password tmppassword --admin --email tmp@example.com ``` 2. **Start Gogs** again, then log in as `tmpuser` in your browser. Navigate to **Admin Panel** > **Users**, click **Edit** next to the original administrator account, and set a new password. diff --git a/docs/docs.json b/docs/docs.json index 8ad05ac28..6383ce824 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -50,7 +50,8 @@ "advancing/webhooks", "advancing/git-lfs", "advancing/custom-templates", - "advancing/localization" + "advancing/localization", + "advancing/cli-reference" ] }, { diff --git a/docs/fine-tuning/configuration-primer.mdx b/docs/fine-tuning/configuration-primer.mdx index 0be18ebc7..d0c73d698 100644 --- a/docs/fine-tuning/configuration-primer.mdx +++ b/docs/fine-tuning/configuration-primer.mdx @@ -71,7 +71,7 @@ The work directory (parent of `custom/`) can also be overridden with `GOGS_WORK_ Every Gogs subcommand accepts `-c, --config` to point to a configuration file at a non-default location: ```bash -./gogs web --config /etc/gogs/app.ini +gogs web --config /etc/gogs/app.ini ``` ### What lives in `custom/` diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 694af3b8d..f3c68d0ca 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -57,7 +57,7 @@ If you choose to use MySQL or PostgreSQL as your database backend, you need to f Release archives containing `mws` come with built-in Windows service support. If you prefer to manage the service using [NSSM](https://nssm.cc), download the standard version instead. - Once extracted the archive, run `./gogs web` to start the server. Use `./gogs web --help` to see all available options. + Once extracted the archive, run `gogs web` to start the server. Use `gogs web --help` to see all available options. Two types of Docker images are provided: