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

NOTE: Refer to config.sample.toml for the latest example configuration or config.rs.
[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
"""