hanyixuanten/php-git-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

2 Releases 2 Tags

RSS Feed
  • v1.0 c84ab0542d
    Compare

    v1.0 Stable

    hanyixuanten released this 2026-08-09 19:09:18 +08:00 | 16 commits to main since this release

    Full Changelog: https://github.com/hanyixuanten/git-server-php/commits/v1.0

    PHP Git Server v1.0.0

    一个可在服务器无法执行 git 命令时，使用纯 PHP 提供 Git Smart HTTP 与 Dumb HTTP 服务的轻量级 Git 服务器。

    A lightweight Git server that provides Smart HTTP and Dumb HTTP services through pure PHP when the server cannot execute the git command.

    中文

    核心功能

    • 支持通过 HTTP 发布显式配置的 bare Git 仓库。
    • 支持 clone、fetch、pull 和 push。
    • 支持远程分支和标签的创建、更新与删除。
    • Git CLI 可用时，使用标准 git-upload-pack 和 git-receive-pack。
    • Git CLI 或 proc_open 不可用时，自动切换到纯 PHP Git 协议后端。
    • 无 Composer 依赖，最低支持 PHP 7.4。

    纯 PHP Smart HTTP

    原生 PHP 后端实现了 Git Smart HTTP 的主要服务端能力：

    • GET /info/refs?service=git-upload-pack
    • POST /git-upload-pack
    • GET /info/refs?service=git-receive-pack
    • POST /git-receive-pack
    • pkt-line 编码、解码和特殊数据包处理。
    • Git protocol v0/v1 风格的 refs 与 capabilities 广告。
    • want、have、ACK 和 NAK 协商。
    • side-band-64k 数据传输。
    • SHA-1 loose object 读取、写入和哈希校验。
    • pack index v2 读取。
    • pack v2 解析与生成。
    • OFS_DELTA 和 REF_DELTA 展开。
    • commit、tree、blob、annotated tag 对象处理。
    • commit、tree 和 tag 可达性遍历。
    • 限制客户端只能请求已发布 refs 可达的对象。

    原生 Push

    • 支持首次向空仓库 push。
    • 支持分支和标签的创建、更新与删除。
    • 校验 pack SHA-1 checksum 和对象 ID。
    • 校验提交、目录、文件和标签之间的对象连通性。
    • 分支 ref 只能指向 commit 对象。
    • 默认拒绝 non-fast-forward 分支更新。
    • 可通过 allow_non_fast_forward 显式允许强制更新。
    • 使用 ref .lock 文件和 old OID 比较避免并发覆盖。
    • 支持 loose refs 与 packed-refs。
    • 拒绝重复 ref 命令和 ref 文件/目录命名空间冲突。
    • 支持 report-status、delete-refs、side-band-64k 和 ofs-delta。
    • 支持按仓库限制请求大小、对象大小和 pack 对象数量。

    Dumb HTTP

    保留完整的只读 Dumb HTTP 兼容路径：

    • HEAD
    • info/refs
    • objects/info/packs
    • objects/info/alternates
    • objects/info/http-alternates
    • loose objects
    • pack 文件
    • pack index
    • loose refs
    • packed refs
    • annotated tag peeled refs

    仓库管理

    • 首页列出允许读取的仓库。
    • 显示 clone URL、默认分支、分支数量、标签数量和 push 权限。
    • 支持从首页创建 bare 仓库。
    • Git 不可用时通过纯 PHP 初始化标准 SHA-1 bare 仓库。
    • 新仓库默认分支为 main。
    • 使用 CSRF token 保护仓库创建表单。
    • 使用创建锁、临时目录和原子重命名避免并发覆盖。
    • 自动发现受控目录下的 .git 仓库。
    • 静态仓库配置优先于自动发现的仓库。

    权限与安全

    每个仓库可以独立配置：

    • read
    • push
    • require_auth
    • branches
    • tags
    • other_refs
    • allow_non_fast_forward
    • max_request_bytes
    • max_object_bytes
    • max_pack_objects

    其他安全措施：

    • push 默认关闭。
    • 可要求 Web 服务器提供可信的 REMOTE_USER。
    • 仓库路径经过 realpath() 和目录边界检查。
    • 不根据 URL 拼接任意文件系统路径。
    • 拒绝非法 ref 名称和目录穿越。
    • 支持 push 请求落盘和大小限制。
    • immutable Git 对象使用长期 HTTP 缓存。
    • refs 和协议响应使用 no-cache。
    • 设置 X-Content-Type-Options: nosniff。
    • 首页使用 Content Security Policy。
    • 验证 Host header 后才生成绝对 clone URL。
    • 支持安全会话 Cookie、HttpOnly、SameSite 和 HTTPS Secure 属性。

    原生后端限制

    以下功能当前需要服务器安装 Git：

    • SHA-256 仓库的完整 Smart HTTP 支持。
    • Git protocol v2 专属命令。
    • shallow clone 和 shallow fetch。
    • partial clone 与 object filter。
    • push certificate 和签名验证。
    • Git hooks。
    • Git maintenance、repack 和 garbage collection。

    原生 PHP 多 ref push 会先锁定并校验所有 refs，但最终 ref 文件仍逐项提交，不提供文件系统级事务回滚。

    English

    Core Features

    • Publishes explicitly configured bare Git repositories over HTTP.
    • Supports clone, fetch, pull, and push.
    • Supports remote branch and tag creation, updates, and deletion.
    • Uses standard git-upload-pack and git-receive-pack when Git CLI is available.
    • Automatically switches to the native PHP backend when Git CLI or proc_open is unavailable.
    • Requires no Composer dependencies and supports PHP 7.4 or newer.

    Native PHP Smart HTTP

    The native backend implements the primary Git Smart HTTP server operations:

    • GET /info/refs?service=git-upload-pack
    • POST /git-upload-pack
    • GET /info/refs?service=git-receive-pack
    • POST /git-receive-pack
    • pkt-line encoding, decoding, and special packet handling.
    • Protocol v0/v1-style ref and capability advertisements.
    • want, have, ACK, and NAK negotiation.
    • side-band-64k transport.
    • SHA-1 loose object reading, writing, and hash validation.
    • Pack index v2 reading.
    • Pack v2 parsing and generation.
    • OFS_DELTA and REF_DELTA resolution.
    • Commit, tree, blob, and annotated tag handling.
    • Commit, tree, and tag reachability traversal.
    • Restricts wants to objects reachable from advertised refs.

    Native Push

    • Supports the first push to an empty repository.
    • Supports branch and tag creation, updates, and deletion.
    • Validates pack SHA-1 checksums and object IDs.
    • Validates object graph connectivity.
    • Requires branch refs to point to commit objects.
    • Rejects non-fast-forward branch updates by default.
    • Forced branch rewrites can be enabled with allow_non_fast_forward.
    • Uses ref lock files and old-OID comparisons to prevent concurrent overwrites.
    • Supports loose refs and packed-refs.
    • Rejects duplicate ref commands and file/directory namespace conflicts.
    • Supports report-status, delete-refs, side-band-64k, and ofs-delta.
    • Provides per-repository request, object-size, and pack-object limits.

    Dumb HTTP

    A complete read-only Dumb HTTP compatibility path remains available:

    • HEAD
    • info/refs
    • objects/info/packs
    • objects/info/alternates
    • objects/info/http-alternates
    • Loose objects
    • Pack files
    • Pack indexes
    • Loose refs
    • Packed refs
    • Peeled annotated tag refs

    Repository Management

    • Lists readable repositories on the home page.
    • Displays clone URLs, default branches, branch and tag counts, and push access.
    • Creates bare repositories from the home page.
    • Initializes standard SHA-1 bare repositories through pure PHP when Git is unavailable.
    • Uses main as the default branch.
    • Protects repository creation with CSRF tokens.
    • Uses creation locks, temporary directories, and atomic renames.
    • Automatically discovers .git repositories in a managed directory.
    • Gives static repository definitions precedence over discovered repositories.

    Access Control and Security

    Each repository can configure:

    • read
    • push
    • require_auth
    • branches
    • tags
    • other_refs
    • allow_non_fast_forward
    • max_request_bytes
    • max_object_bytes
    • max_pack_objects

    Additional protections include:

    • Push is disabled by default.
    • Authentication can require a trusted web-server REMOTE_USER.
    • Repository paths are protected with realpath() containment checks.
    • Filesystem paths are never constructed directly from arbitrary URLs.
    • Invalid refs and path traversal are rejected.
    • Push requests can be spooled and size-limited.
    • Immutable Git objects receive long-lived HTTP caching.
    • Ref and protocol responses use no-cache headers.
    • Responses use X-Content-Type-Options: nosniff.
    • The home page uses Content Security Policy.
    • Absolute clone URLs are generated only after Host header validation.
    • Session cookies support HttpOnly, SameSite, and HTTPS Secure attributes.

    Native Backend Limitations

    The following features currently require an installed Git executable:

    • Complete Smart HTTP support for SHA-256 repositories.
    • Protocol v2-only commands.
    • Shallow clone and shallow fetch.
    • Partial clone and object filters.
    • Push certificates and signature verification.
    • Git hooks.
    • Git maintenance, repacking, and garbage collection.

    Native multi-ref pushes lock and validate all refs before committing, but final ref files are still committed individually and do not provide filesystem-level transactional rollback.

    Downloads