BookStack vs Git

What BookStack is

BookStack is an MIT-licensed, self-hosted documentation application built around shelves, books, optional chapters and pages. It provides role and content-level permissions, multiple enterprise authentication options and a permission-aware REST API, but the operator remains responsible for the PHP and database stack, upgrades, filesystem permissions, security configuration and complete database-plus-file backups.

What Git is

Git is GPLv2-licensed distributed version-control software that stores snapshots, branches, tags and repository history locally and exchanges objects with other repositories through supported transports. Git itself is not a hosted collaboration service: accounts, pull requests, access policy, off-machine backups, issue tracking and CI require separate infrastructure or a hosting provider.

What BookStack is built to do

Book hierarchy

Organizes page content within optional chapters, books and reusable bookshelves.

Roles and permissions

Combines system roles with content-level overrides and inherited controls.

Federated authentication

Documents OIDC, SAML 2.0 and LDAP configuration for self-hosted instances.

REST API

Provides token-authenticated JSON endpoints governed by the API user's permissions.

What Git is built to do

Commits and history

Records content snapshots and parent relationships in a local object database.

Branches and merges

Maintains movable branch references and combines divergent lines of development.

Distributed remotes

Fetches from and pushes to separately administered repositories over supported transports.

Clone controls

Supports full, shallow, sparse, partial, bare and mirror clone modes with different tradeoffs.

Choose BookStack if

• Internal handbooks, runbooks and technical knowledge bases with a clear hierarchy
• Organizations needing self-hosting, role controls and supported identity integrations
• Teams that can automate upgrades, database and file backups, and restore drills

Skip BookStack if

• You need a vendor-operated SaaS with no infrastructure responsibility
• Your information model cannot fit shelves, books, chapters and pages
• You cannot preserve the database, uploads, configuration and original APP_KEY together

Choose Git if

• Text-oriented source repositories needing local history and branching
• Teams selecting their own hosting and code-review workflow
• Projects whose contributors can follow an agreed merge, rebase and recovery policy

Skip Git if

• You expect user management, pull requests, CI and remote backups from the core installation
• The primary assets are large binaries and no suitable storage strategy has been selected
• The team cannot govern credentials, destructive history changes and repository recovery

BookStack: pros & cons

• Predictable structure: Shelves, books, chapters and pages give teams a constrained documentation hierarchy.
• Granular access: Roles can be combined and overridden at shelf, book, chapter or page level.
• Authentication choices: Official administration docs cover OpenID Connect, SAML 2.0 and LDAP.
• Automation surface: The REST API covers content and administrative resources while enforcing the API user's roles and permissions.
• Self-hosting burden: PHP, MySQL or MariaDB, web-server configuration, updates and monitoring are operator responsibilities.
• Manual recovery design: There is no built-in full backup and restore; both database records and instance files must be protected.
• Key dependency: Restores need the original APP_KEY for encrypted features such as multi-factor credentials.
• Hierarchy trade-off: The book metaphor is approachable but may constrain teams needing free-form graphs or complex publishing workflows.

Git: pros & cons

• Distributed history: A normal clone creates local repository objects and remote-tracking branches for offline work.
• Branching tools: Branch, switch, merge, rebase and worktree commands support multiple development patterns.
• Transport choice: Current documentation covers SSH, Git, HTTP and HTTPS repository URLs.
• Open-source core: Git is distributed under GPL version 2 without a software license fee.
• Hosting not included: Git alone does not supply identities, review UI, protected branches, CI or remote availability.
• History-changing commands: Reset, rebase, filter and force-push workflows need explicit team policy and recovery knowledge.
• Credential handling is externalized: Git delegates secure credential storage to configured helpers or platform mechanisms.
• Repository design matters: Large histories, binaries, submodules and shared-object optimizations introduce additional maintenance choices.