3.9 KiB
Code Overview
This document seeks to outline how the project is organized, to help anyone who wants to use or modify the code.
index.php
index.php is the file that always runs when a client requests a page. It then loads other PHP files from the src/ folder to build the page that the user has requested.
src/utils.php
utils.php is a collection of useful functions for this project. Any function called in this project that's not native to PHP is defined in utils.php, and these functions are organized into two categories - string processing (which do not require system calls to git) and git methods (which do) - and organized alphabetically within their category.
src/pages/
PHP files in src/pages give instructions for specific types of pages:
- home.php: The homepage, which lists the repositories. Located at https://example.com/
- repo.php: The front page of a repository. This is basically a tree page, with a preview of the readme (if applicable). Located at https://example.com/projectname/
- tree.php: A directory within the project, which holds its own files. Located at https://example.com/projectname/tree/main/path/to/directory/
- blob.php: A file within the project. A preview of the file is displayed, if possible. Located at https://example.com/projectname/blob/main/path/to/file/
- raw.php: The raw data of a file. Currently should support jpg, png, gif, and text data correctly. Located at https://example.com/projectname/raw/main/path/to/file/
- commits.php: Lists the commit history. Located at https://example.com/projectname/commits/
- commit.php: Shows a single commit with an overview, and the changes ade to each file. Located at https://example.com/projectname/commit/commithash/
- tags.php: Shows a list of the tags and the date they were made. Right now this is not super helpful, but in the future I want to be able to show the whole repository at a given commit, and tags will be more useful then. Located at https://example.com/projectname/tags/
src/parts/
PHP files in src/parts/ are sections of a page, which may be reused often. The src/pages/ files generally include multiple src/parts/ files.
- header.php: The top of the HTML page. This file determines the theme to use.
- description.php: Lists the current path, clickable to any point in the path (example.com / projectname / path / to / current). Lists the project description beneath this.
- menu.php: Links to different parts of the repository: Code, Commits, Tags, License (if present and detected).
- table.php: Lists the subdirectories and files in the current directory in a table, with links to their page and their most recent commit.
- preview.php: Attempts to display a file. If it is a .md file, it will try to render it as Markdown using pandoc.
- footer.php: The bottom of the HTML page. This file also adds a link to the source code. You may remove or modify this link in your version, but you must prominently offer the source code of the version running on your server to any user who connects to your site. See modifying.md for more information.
config.ini
This is the configuration file. (It should be copied from templates/config.ini.template) Lines beginning with a semicolon are comments and will not be interpreted. Modify this to show your site title, set the path to your repositories, and change the theme.
themes/
CSS files in the themes/ directory are theme options for the page. To add your own theme, add a new .css file (example.css), and to enable that theme, change the value of "theme" in config.ini (theme = "example").
If you just want to change the color scheme, this is easy to do. Just change the values of --primary-color, --secondary-color, and --background-color at the top of the file.
git.conf
This is an Apache configuration file to add a virtualhost for this service. It should be copied from templates/httpd-git.conf.template. It contains all necessary configurations, so an .htaccess file should not be needed.