-rw-r--r-- DOCUMENTATION.md
1 Documentation 2 ============= 3 4 `gitja` is a tool that reads from locally hosted or cloned git repositories and 5 generates static HTML pages using their data and 6 [Jinja](https://jinja.palletsprojects.com) templates. 7 8 Usage 9 ----- 10 11 ### Configuration file 12 13 gitja is configured using a [dhall](https://dhall-lang.org) config file. The 14 [example config](https://github.com/m-col/gitja/blob/master/config.dhall) is a 15 good place to start, or alternatively create one in the current folder by 16 running `gitja -t`. 17 18 It requires the following settings: 19 20 | Setting | Description | 21 | ---------- | --------------------------------------------------------------- | 22 | `repos` | A list of folders containing your git repositories. | 23 | `scan` | Whether `repos` lists repos or folders containing nested repos. | 24 | `template` | The folder containing the template (see below). | 25 | `output` | Where to put the generated files. | 26 | `host` | The host URL, which is needed for creating links. | 27 28 If `scan` is `True`, then gitja will look for git repositories in folders 29 nested within those listed in `repos`. Otherwise, the folders in `repos` are 30 assumed to be repositories themselves. 31 32 Then, pass the config file to gitja. 33 34 ### CLI 35 36 See the CLI help message for usage: 37 38 Usage: gitja [-c|--config CONFIG] [-q|--quiet] [-f|--force] [-t|--template] 39 [-v|--version] 40 🐙 Templated web page generator for your git repositories 41 42 Available options: 43 -c,--config CONFIG Configuration file to use (Default: ./config.dhall). 44 -q,--quiet Suppress non-error output. 45 -f,--force Force regeneration of all files. 46 -t,--template Create a template and config in the current folder. 47 -v,--version Print the gitja's version. 48 -h,--help Show this help text 49 50 Note the `force` flag. By default, gitja will not generate new output for 51 commits to save time. This flag will force regeneration of all files, which 52 would be needed if changes have been made to the template. 53 54 Templates 55 --------- 56 57 A base template can be created in the current folder by running `gitja -t`. 58 This can be used as a starting point to creating your own template. 59 60 ### Folder structure 61 62 The files that gitja outputs are generated using 63 [ginger](https://ginger.tobiasdammers.nl) template files, which use the 64 [Jinja](https://jinja.palletsprojects.com) templating language. If these are 65 new to you, it may be enough to skim through some of the examples in the 66 [templates](https://github.com/m-col/gitja/tree/master/templates) folder, 67 otherwise the ginger docs can be very helpful to see what is supported. 68 69 Templates are a folder containing a number of ginger template files. There are 70 5 "scopes", each making available a unique set of variables storing information 71 about the git repositories. Each template file has access to a single one of 72 these scopes. The structure of the template folder determines the scopes of the 73 files contained therein. 74 75 To illustrate, this is the expected structure: 76 77 template/ 78 i_can_have_any_name.html 79 and_there_can_be_any_number.html 80 some_might_be_ginger_includes.html.include 81 non_html_is_fine.css 82 repo/ 83 inside_this_folder.html 84 two_names_are_special.html 85 foreach.blob.html 86 foreach.commit.html 87 foreach.tree.html 88 89 The top-level folder, here `template`, is that which is specified in the config 90 file. 91 92 Files ending in ".html" directly within that folder have access to the *index 93 scope*, and are each parsed exactly once and output into the output directory 94 with the same name. 95 "[include](https://ginger.tobiasdammers.nl/guide/syntax/statements/#include)" 96 files are never copied but can be used to assist in templating. 97 98 The special folder "repo" has access to the *repo scope*, which exposes 99 information pertaining to a single git repository. The template files contained 100 within this folder are parsed and output once per git repository. 101 102 The exceptions to this are the three special template files with the names 103 "foreach.blob.html", "foreach.commit.html" and "foreach.tree.html" - named to 104 make clear that, unlike everything else in "repo/", these are parsed and 105 output once *per* blob, commit or tree found anywhere in the repository, at 106 any depth, rather than once per repository. These have access to the *blob 107 scope*, *commit scope* and *tree scope* respectively (a submodule reference 108 is currently treated as a blob whose content is its target commit hash, 109 rather than as its own scope). 110 111 The resulting folder structure found in `output` will look like this (if 112 `repos` only contains gitja): 113 114 output/ 115 i_can_have_any_name.html 116 and_there_can_be_any_number.html 117 non_html_is_fine.css 118 gitja/ 119 inside_this_folder.html 120 two_names_are_special.html 121 blob/ 122 LICENSE.html 123 Makefile.html 124 ... 125 commit/ 126 0a18f38bb5c398bd192a6268281fc6abefaedd63.html 127 0a7601059956d9c4d395f5d08e8cf48a515d080f.html 128 ... 129 tree/ 130 src.html 131 ... 132 ... 133 134 ### Static files 135 136 Files in the template folder that do not end in ".html" or ".include" or are 137 symbolic links, as well as directories that are not called "repo", are 138 considered static content. These are copied unchanged (i.e. symbolic links are 139 copied as symbolic links) to the output folder. This is useful for putting CSS, 140 images etc into the output. 141 142 Similarly, any static content found within the template's "repo/" folder is 143 copied unchanged into the output folder for every repository. 144 145 ### Scopes 146 147 The variables available within each scope are listed here for reference: 148 149 | Scope | Variable | Description | 150 | ------ | --------------- | ----------------------------------------------------- | 151 | Index | host | The string from the `host` config option. | 152 | | repositories | A list of all of the git repositories. | 153 | Repo | | *In addition to the variables from the index scope...*| 154 | | name | The repository name, taken from its folder name. | 155 | | description | The repository's description (see below). | 156 | | commits | A list of the repository's commits. | 157 | | tree | A list of the repository root tree's entries. | 158 | | entries | A flat list of *every* entry (blob or tree) at any depth in the repository, like `git ls-tree -r -t`. | 159 | | blobs | A flat list of *every* blob (file) in the repository. | 160 | | trees | A flat list of *every* tree (directory) at any depth in the repository. | 161 | | tags | A list of the refs corresponding to tags. | 162 | | branches | A list of the refs corresponding to branches. | 163 | | readme | The repository's readme file, if it has one. | 164 | | license | The repository's license file, if it has one. | 165 | Blob | | *In addition to the variables from the Repo scope...* | 166 | | blob | A single blob (file). | 167 | Commit | | *In addition to the variables from the Repo scope...* | 168 | | commit | A single commit. | 169 | Tree | | *In addition to the variables from the Repo scope...* | 170 | | tree | A single tree (directory) - shadows the repo-scope `tree`, since a tree page is itself scoped to one tree. | 171 172 As in [Jinja](https://jinja.palletsprojects.com), a list can be accessed with 173 indexing, and attributes can be accessed using a dot notation. For example, a 174 `repository` exposes an attribute called "name", so to access the name of the 175 first repository from within the index scope you would do 176 `repositories[0].name`. 177 178 Here is the reference of attributes available on the variables that have them: 179 180 | Object | Attribute | Description | 181 | ---------- | ---------------- | -------------------------------------------------------- | 182 | repository | name | The repository's name, taken from the folder name. | 183 | | description | The repository's description (see below). | 184 | | head | The current git commit. | 185 | | updated | The time when the current commit was committed. | 186 | blob/tree | path | The path relative to the repository root. | 187 | | name | The name of the blob or tree. | 188 | | href | The name of the HTML file for this blob or tree. | 189 | | contents | The blob's contents (n/a for a tree). | 190 | | mode | Directory, Plain, Executable, Symlink or Submodule. | 191 | | mode\_octal | Mode in octal form e.g. "00644" for plain files. | 192 | | mode\_symbolic | Mode in symbolic form e.g. ""-rw-r--r--" for plain files.| 193 | | is\_directory | A boolean, useful for ginger conditionals. | 194 | | is\_binary | A boolean, tells you if the contents can be rendered. | 195 | | tree | This tree's direct contents (n/a for a blob). | 196 | | entries | A flat list of *every* entry (blob or tree) at any depth under this tree (n/a for a blob). | 197 | ref | name | The tag or branch name. | 198 | | commit | The commit pointed to by the tag or branch. | 199 | commit | id | The SHA of the given commit. | 200 | | href | The name of the HTML file for this commit. | 201 | | title | The commit message title. | 202 | | body | The commit message body. | 203 | | message | The entire message, including both title and body. | 204 | | diff | The list of diff objects for this commit. | 205 | | author | The commit author. | 206 | | committer | The committer. | 207 | | author\_email | The email address of the author. | 208 | | committer\_email | The email address of the committer. | 209 | | authored | The timestamp from when it was written. | 210 | | committed | The timestamp from when it was committed to this branch. | 211 | | encoding | The commit encoding. | 212 | | parent | The SHA of the parent commit. | 213 | diff | new\_file | The name of the file after the diff. | 214 | | old\_file | The name of the file before the diff. | 215 | | status | The type of the change (see below). | 216 | | hunks | The list of modified hunks for this file. | 217 | hunk | header | The hunk's header e.g. "@@ -2,44 +2,22 @@". | 218 | | lines | The list of lines that form this hunk. | 219 | line | text | The line, possibly prefixed by `+` or `-`. | 220 | | class | `"add"`, `"sub"` or `"def"` -- useful for CSS. | 221 222 Note: 223 224 - Some attributes point to other objects that have attributes. For example, 225 `branches[0].commit.parent` will work as expected. 226 - "file" includes directories and symbolic links. 227 228 ### Diffs 229 230 Each commit has a corresponding list of diffs. Each diff corresponds to the 231 changes made to a single file. A diff's `new_file` and `old_file` will differ 232 only if the file was renamed. The `status` can be one of: Unmodified, Added, 233 Deleted, Modified, Renamed, Copied, Ignored, Untracked, TypeChange. 234 235 A diff contains a series of 'hunks' that represent contiguous blocks of text 236 within the file that were modified in some way. Each has a header that 237 indicates where the hunk is in the file. The hunks each also expose a list of 238 _lines_, each of which exposes the text content of that line, as well as a 239 'class'. The class is a convenience attribute that can be used to set the CSS 240 class of the line without needing to parse the line text from within a template 241 file. This makes it easier to style additions and subtractions from other (def 242 for default) lines. 243 244 ### Descriptions 245 246 Each repository can have a description that is available in the templates. This 247 is how the description for a given respository is determined: 248 249 1. Look for a file at `repo/description`, and if found read from there. 250 2. Otherwise, look for a file at `repo/.git/description`, and if found read from there. 251 2. Otherwise, simply use the repository folder's name. 252 253 Questions? 254 ---------- 255 256 If any of this is unclear or could be improved, please do feel free to post an 257 issue on GitHub (or contact me another way). Contributions of code and docs are 258 also warmly welcome. 259