What is Forgejo-aneksajo about?

It is a (temporary) fork of Forgejo that adds an integration with git-annex. This makes Forgejo a suitable service for hosting very large collections of data (beyond the TB range).

The patch set is tracking the latest Forgejo releases, with the aim to propose it for integration into Forgejo proper eventually.

Features and differences compared to Forgejo proper

Markup rendering

When rendering an annexed file and a renderer that has with IS_INPUT_FILE=true, no temporary content copies are made. This allows for raising the MAX_DISPLAY_FILE_SIZE threshold from the default 8MB (even to several GB, if needed). Without this, Forgejo would not attempt to render a file exceeding the threshold, even if it would only require to read a small header.

In addition to the standard environment for external markup renderers (see https://forgejo.org/docs/latest/admin/config-cheat-sheet/#markup-markup), an additional environment variable GITEA_RELATIVE_PATH is set, which contains the original filename (with relative path) within the repository. This can be useful for an implementation to see original file name extensions, or other context information encoded in the path.

See https://codeberg.org/matrss/forgejo-aneksajo/pulls/36

How is the setup different from Forgejo?

Git-annex support is enabled via a new configuration setting

[annex]
ENABLED = true

Details on how remote git-annex commands are allowed to interact with the Forgejo repositories can be configured via the environment settings of git-annex-shell, namely:

• GIT_ANNEX_SHELL_READONLY
• GIT_ANNEX_SHELL_LIMITED
• GIT_ANNEX_SHELL_APPENDONLY
• GIT_ANNEX_SHELL_DIRECTORY

See the git-annex-shell manpage for more information.

How is Forgejo-aneksajo maintained?

Forgejo-aneksajo is a soft fork of Forgejo. The changes done to make it work with git-annex are a set of commits applied on-top of a released Forgejo version.

The forgejo branch of the Forgejo-aneksajo repository is its development branch. This branch contains the current revision of the Forgejo-aneksajo patch set applied on top of the latest Forgejo release.

New changes should go through a pull request and pull requests should target the forgejo branch. A pull request should contain one self-contained bug fix, enhancement or similar that improves the state of things.

Whenever a new Forgejo version is released the forgejo branch is rebased onto that new version in a timely manner, fixing all potential rebase conflicts, testing it, and then force-pushing to the Forgejo-aneksajo repository, where it will be going through the automated CI tests as well. Code changes as part of addressing conflicts should not introduce something new, but only get the patch set back into a compilable state and passing tests. More elaborate changes should go through a pull request.

Releases of Forgejo-aneksajo are tagged from the forgejo branch and follow a versioning scheme of v<x.y.z>-git-annex<n>, where <x.y.z> is the Forgejo version on which this release is based and <n> is a simple revision counter starting at 0 for the first -git-annex release of that Forgejo version. Before a Forgejo-aneksajo release is tagged, it is tested; notably, passing CI is a prerequisite.

Whenever new changes have been merged into the forgejo branch, a new release can be tagged from it by increasing the revision counter.

Features for potential development

• support for PRs with annexed files
• nice diff views (e.g. of images) for data content
• archive downloads with annexed content
• mirrored repositories

How exactly is Forgejo patched?

The patch set for Forgejo-aneksajo is (re)built on each Forgejo release tag. The full diff can be seen by comparing a Forgejo release tag to a corresponding Forgejo-aneksajo release tag of the same upstream version. For example:

git diff v8.0.2..v8.0.2-git-annex0

Added software dependencies

• .forgejo/workflows/testing.yml
• Dockerfile*

Execution of git-annex commands and git-annex/Forgejo integration (core patch)

• cmd/serv.go
• cmd/web.go
• modules/annex/annex.go (added module)
• modules/base/tool.go
• modules/git/blob.go
• modules/git/blob_gogit.go
• modules/git/command.go
• modules/git/repo_blob_gogit.go
• modules/git/tree_entry_gogit.go
• modules/private/serv.go
• routers/private/serv.go
• routers/web/repo/download.go
• routers/web/repo/githttp.go
• routers/web/repo/view.go
• routers/web/web.go
• services/auth/auth.go
• services/auth/basic.go
• services/repository/files/temp_repo.go
• services/repository/files/upload.go

Added configuration switch(es)

• modules/setting/annex.go
• modules/setting/setting.go

Adjustments to git-annex behavior

• Makefile
• modules/util/remove.go

Documentation and examples

• custom/conf/app.example.ini

Localization and UI tweaks

• options/locale/*
• web_src/css/repo.css

Tests

• tests/integration/api_helper_for_declarative_test.go
• tests/integration/git_annex_test.go (added)
• tests/integration/git_helper_for_declarative_test.go

Enable git-annex support in tests

• tests/mysql.ini.tmpl
• tests/pgsql.ini.tmpl
• tests/sqlite.ini.tmpl

Test utilities

• tests/test_utils.go

Changes to give this temporary fork a distinct name

• package-lock.json