Proposal: Remove/replace "web" as the default action for the binary #11265

New Issue

GiteaMirror · 2025-11-02T09:32:46-06:00

GiteaMirror commented

2025-11-02 09:32:46 -06:00

Originally created by @jolheiser on GitHub (Jul 18, 2023).

Feature Description

Currently gitea is just a shortcut for gitea web when invoking the binary. In many cases where a human¹ is running the CLI, I would wager that this is not what they expect or want to do.

I'm creating this proposal to gather feedback from the community, but I think this would potentially make the initial experience less confusing.

We could, if this proposal goes through, more accurately contain the code that generates directories/files to the commands that actually need/expect those things to exist. Of course we should also improve those commands to make them less destructive (or creative) in their own right, but I think this would implicitly help avoid issues such as https://github.com/go-gitea/gitea/issues/25938

As a side-note, my suggestion for a replacement would be gitea help as the shortcut. At least then the default action is to show you the available actions.

Impact

Thankfully the example systemd service already explicitly invokes the web sub-command, so anyone who has copied the command from there should be fine.

The docker run scripts also appear to set this correctly.

The docs also explicitly invoke web.

Nixpkgs is correct.
Alpine is correct.
Arch is correct.
Gentoo is correct.
OpenSUSE is correct.

This means that only those who do not use/copy the above defaults would be affected, and then only those that do not explicitly invoke the web sub-command.

Screenshots

No response

other than our wonderful, very human, and definitely not robot developers who likely run this command a ton when making changes ↩︎

Originally created by @jolheiser on GitHub (Jul 18, 2023). ### Feature Description Currently `gitea` is just a shortcut for `gitea web` when invoking the binary. In many cases where a human[^1] is running the CLI, I would wager that this is **not** what they expect or want to do. I'm creating this proposal to gather feedback from the community, but I think this would potentially make the initial experience less confusing. We could, if this proposal goes through, more accurately contain the code that generates directories/files to the commands that actually need/expect those things to exist. Of course we should also improve those commands to make them less destructive (or creative) in their own right, but I think this would implicitly help avoid issues such as https://github.com/go-gitea/gitea/issues/25938 As a side-note, my suggestion for a replacement would be `gitea help` as the shortcut. At least then the default action is to show you the available actions. ## Impact Thankfully the example [systemd service](https://github.com/go-gitea/gitea/blob/cc73e84fa355fa49e875b2d17319b3da70775e0d/contrib/systemd/gitea.service#L62) already explicitly invokes the `web` sub-command, so anyone who has copied the command from there should be fine. The docker [run](https://github.com/go-gitea/gitea/blob/cc73e84fa355fa49e875b2d17319b3da70775e0d/docker/rootless/usr/local/bin/docker-entrypoint.sh#L16) [scripts](https://github.com/go-gitea/gitea/blob/cc73e84fa355fa49e875b2d17319b3da70775e0d/docker/root/etc/s6/gitea/run#L5) also appear to set this correctly. The [docs](https://docs.gitea.com/installation/install-from-binary#2-running-from-command-lineterminal) also explicitly invoke `web`. [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/e2519d12c83888b8b47509a11f1af5d04f5bce5f/nixos/modules/services/misc/gitea.nix#L582) is correct. [Alpine](https://git.alpinelinux.org/aports/tree/community/gitea/gitea.initd#n7) is correct. [Arch](https://gitlab.archlinux.org/archlinux/packaging/packages/gitea/-/blob/main/gitea.service#L19) is correct. [Gentoo](https://github.com/gentoo/gentoo/blob/e36b7c375189646f888ab42f9620103440b86478/www-apps/gitea/files/gitea.service-r3#L27) is correct. [OpenSUSE](https://build.opensuse.org/package/view_file/devel:tools:scm/gitea/gitea.service?expand=1) is correct. This means that only those who do not use/copy the above defaults would be affected, and then only those that do not explicitly invoke the `web` sub-command. [^1]: other than our wonderful, very human, and definitely not robot developers who likely run this command a ton when making changes ### Screenshots _No response_

GiteaMirror added the type/proposal label 2025-11-02 09:32:46 -06:00

GiteaMirror commented

2025-11-02 09:32:47 -06:00

@wxiaoguang commented on GitHub (Jul 18, 2023):

but I think this would implicitly help avoid issues such as #25938

More contexts: actually it's not related.

The reason behind "#25938" is that the "./gitea --help" is documented to be used to show the "work-path / custom-path / custom-conf". ref: cc73e84fa3/custom/conf/app.example.ini (L15)

To resolve various bugs, Refactor path & config system #25330 starts using the WORK_PATH in app.ini as a stable work-path value. So "./gitea --help" needs to read the "app.ini" to show the correct work-path.

However, Gitea's config system is a mess, the ini file might be rewritten during config loading, and some directories might be created during the loading too.

ps: I am neutral for keeping or removing the "web" as shortcut.

@wxiaoguang commented on GitHub (Jul 18, 2023): > but I think this would implicitly help avoid issues such as #25938 More contexts: actually it's not related. The reason behind "#25938" is that the "./gitea --help" is documented to be used to show the "work-path / custom-path / custom-conf". ref: https://github.com/go-gitea/gitea/blob/cc73e84fa355fa49e875b2d17319b3da70775e0d/custom/conf/app.example.ini#L15 To resolve various bugs, Refactor path & config system #25330 starts using the WORK_PATH in app.ini as a stable work-path value. So "./gitea --help" needs to read the "app.ini" to show the correct work-path. However, Gitea's config system is a mess, the ini file might be rewritten during config loading, and some directories might be created during the loading too. ---- ps: I am neutral for keeping or removing the "web" as shortcut.

GiteaMirror commented

2025-11-02 09:32:47 -06:00

@jolheiser commented on GitHub (Jul 18, 2023):

fwiw I also entirely agree with the above, other commands need some work to help stabilize when/how Gitea writes to files.

The core of the proposal is simply that the web sub-command is probably an unexpected entry-point for someone running the base gitea binary.

In the earlier days it made more sense, as Gitea was largely built to be invoked programmatically. Now, however, the CLI includes various sub-commands where someone is more likely to experiment or use other utilities.

@jolheiser commented on GitHub (Jul 18, 2023): fwiw I also entirely agree with the above, other commands need some work to help stabilize when/how Gitea writes to files. The core of the proposal is simply that the `web` sub-command is probably an unexpected entry-point for someone running the base `gitea` binary. In the earlier days it made more sense, as Gitea was largely built to be invoked programmatically. Now, however, the CLI includes various sub-commands where someone is more likely to experiment or use other utilities.

GiteaMirror commented

2025-11-02 09:32:48 -06:00

@wxiaoguang commented on GitHub (Jul 18, 2023):

As the first step, I think we can remove the "web" related options from the default command

This is done in Refactor to use urfave/cli/v2 #25959

Before, many "web"-only options pollute the global options:

$ ./gitea --help
...
GLOBAL OPTIONS:
   --help, -h                     show help
   --custom-path value, -C value  Set custom path (defaults to '{WorkPath}/custom')
   --config value, -c value       Set custom config file (defaults to '{WorkPath}/custom/conf/app.ini')
   --work-path value, -w value    Set Gitea's working path (defaults to the Gitea's binary directory)
   --port value, -p value         Temporary port number to prevent conflict (default: "3000")
   --install-port value           Temporary port number to run the install page on to prevent conflict (default: "3000")
   --pid value, -P value          Custom pid file path (default: "/run/gitea.pid")
   --quiet, -q                    Only display Fatal logging errors until logging is set-up
   --verbose                      Set initial logging to TRACE level until logging is properly set-up
   --version, -v                  print the version

After:

$ ./gitea --help
...
GLOBAL OPTIONS:
   --help, -h                     show help
   --version, -v                  print the version
   --custom-path value, -C value  Set custom path (defaults to '{WorkPath}/custom')
   --config value, -c value       Set custom config file (defaults to '{WorkPath}/custom/conf/app.ini')
   --work-path value, -w value    Set Gitea's working path (defaults to the Gitea's binary directory)

@wxiaoguang commented on GitHub (Jul 18, 2023): As the first step, I think we can remove the "web" related options from the default command This is done in Refactor to use urfave/cli/v2 #25959 Before, many "web"-only options pollute the global options: ``` $ ./gitea --help ... GLOBAL OPTIONS: --help, -h show help --custom-path value, -C value Set custom path (defaults to '{WorkPath}/custom') --config value, -c value Set custom config file (defaults to '{WorkPath}/custom/conf/app.ini') --work-path value, -w value Set Gitea's working path (defaults to the Gitea's binary directory) --port value, -p value Temporary port number to prevent conflict (default: "3000") --install-port value Temporary port number to run the install page on to prevent conflict (default: "3000") --pid value, -P value Custom pid file path (default: "/run/gitea.pid") --quiet, -q Only display Fatal logging errors until logging is set-up --verbose Set initial logging to TRACE level until logging is properly set-up --version, -v print the version ``` After: ``` $ ./gitea --help ... GLOBAL OPTIONS: --help, -h show help --version, -v print the version --custom-path value, -C value Set custom path (defaults to '{WorkPath}/custom') --config value, -c value Set custom config file (defaults to '{WorkPath}/custom/conf/app.ini') --work-path value, -w value Set Gitea's working path (defaults to the Gitea's binary directory) ```

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#11265