Initial Configuration
After following the installation you need to setup your configuration file and initialize the database.
User Based Installation
mkdir ~/.config/ayllu
ayllu config generate > ~/.config/ayllu/config.yaml
# open up config.yaml in your favorite editor and configure at least one
# collection
vim ~/.config/ayllu/config.yaml
# now verify the config is valid
ayllu config display
# initialize and migrate the database
ayllu migrate
# launch the web server
ayllu serve
Collections
Collections are simply a directory on your file system that contains zero or more Git repositories. They can be structured in whichever way is suitable for your personal workflow.
# On my system I keep active projects in a directory called "projects"
[[collections]]
name = "projects"
description = "active projects"
path = "/home/kevin/repos/projects"
# And another directory of archived projects that I call "the attic"
[[collections]]
name = "attic"
description = "projects stowed away in the attic"
path = "/home/kevin/repos/attic"
# it's also possible to create hidden collections that aren't showed in the
# collections index page but will be rendered if you know the link to them.
# If you want to restrict access completely you'll need to employ basic auth
# or similiar in your webserver.
[[collections]]
name = "private"
description = "my private code, no looking!"
path = "/home/kevin/repos/private"
Running Jobs
Once Ayllu has been configured and the server is running you'll want to run jobs against your repositories. Jobs do things like compute authorship stats and determine code composition. Keep in mind that jobs are distinct from builds. Jobs perform internal actions that allow Ayllu to function while builds are for running codebase specific workflows.
Most jobs are run via git hooks
# ayllu's internal job server will be listening on a unix socket
ss -xlp |grep ayllu
u_str LISTEN 0 1024 /run/user/1000/ayllu.sock 305937 * 0 users:(("ayllu",pid=70917,fd=14))
cd ~/repos/projects/ayllu
# run against your repository
# depending on the number of commits this can take a considerable amount of
# time to run as it needs to perform computations against each commit.
ayllu jobs run .
Tree Sitter
Syntax highlighting in the web interface is implemented with tree-sitter. Instead of embedding and compiling potentially hundreds of individual shared modules for each language you can install languages you are interested in via your operating system's package manager. Unfortunately, not all parsers are consistently packaged and thus it is possible to override system defaults as described below.
Customizing Shared Module Paths
Normally tree-sitter parsers should have the following layout:
# compiled shared modules
/usr/lib/libtree-sitter-$language.so
# supplemental query files
/usr/share/tree-sitter/queries/$language/[highlights|injections|locals].scm
By default Ayllu will attempt to load parsers and query files from those directories.
Example Custom Configuration
[tree-sitter]
# specify the base path to search for libtree-sitter-$language.so
base_path = "/usr/lib"
# directory of syntax queries
queries_path = "/usr/share/tree-sitter/queries"
Adding a Additional Queries
An additional path to look for queries can also be added:
[tree-sitter]
queries_extras_path = "/etc/ayllu/queries"
Adding Additional Parsers
If you want to add a custom parser that's installed at a non-standard path you can do that too. This can be useful for parsers that aren't packaged on your system and also for custom programming languages.
[[tree-sitter.parsers]]
name = "fuu-lang"
shared_object = "/etc/ayllu/parsers/libtree-sitter-fuu.so"
highlight_query = "/etc/ayllu/queries/fuu/highlights.scm"
locals_query = "/etc/ayllu/queries/fuu/locals.scm"
injections = "/etc/ayllu/queries/fuu/injections.scm"
Language Detection & Syntax Highlighting
Ayllu determines which language is being rendered by file extension, file name, or an "alias" in the case of a markdown code block.
Language Mapping
Sometimes you want one language to be detected and presented as something different. For instance by default Ayllu will detect hello.ml as a Standard ML file, but you can override this to OCaml with a mapping.
[languages]
[languages.mappings]
"Standard ML" = "OCaml"
Custom Languages
If you're the author of a programming language and want Ayllu to detect it based on file extensions you can add an additional language in your config file.
# append the following in your config.toml
[[ languages.extras ]]
name = "BazQux"
extensions = [".baz", ".qux", ".bq"]
# any file with this name will be detected as BazQux
filename = [".bazscript"]
# deep pink
color = "#ff1493"
You can also use the languages section to modify existing languages, for instance if for some reason you didn't like the default colors associated with a particular programming language, you can adjust it here.
# append the following in your config.toml
[[ languages.extras ]]
name = "go"
# Go is pink!
color = "#ff1493"
Adding Custom Tree Sitter Highlights
You can override system installed tree-sitter highlights in the Ayllu configuration file. For example we can add two new highlight queries to the diff parser called @addition and @removal. With these enabled Ayllu will paint the relevant code sections with CSS classes ts_addition and ts_removal which you can style in theme configurations.
[tree-sitter.highlights]
diff = """
; used to highlight diffs in the UI
[(addition) (new_file)] @addition
[(deletion) (old_file)] @removal
(commit) @constant
(location) @attribute
(command) @variable.builtin
"""
Mirroring
Git mirrors will be automatically detected by looking at git configuration to determine if the repository has a mirror = true flag present in any of it's configured remotes. If any remote is flagged as a mirror then the repository will be considered a mirror. Mirror repositories will not be listed in RSS feeds, be subject to certain jobs types, or be available in the remote API.
Creating a Mirror
The simplest way to create a mirror is by cloning a repository with the --mirror flag. For example: git clone https://ayllu-forge.org/ayllu/ayllu --mirror will result in a git config such as:
[remote "origin"]
url = https://ayllu-forge.org/ayllu/ayllu
fetch = +refs/*:refs/*
mirror = true