From 9c67a4204ac627066ef3a4c92df136d3f57f06f1 Mon Sep 17 00:00:00 2001 From: Michal S Date: Tue, 27 Sep 2022 23:57:56 +0100 Subject: [PATCH] Adds Malachite config --- en/malachite/common-features.mdx | 10 +++---- en/malachite/getting-started.mdx | 51 ++++++++++++++++++++++++++++++++ en/malachite/repository-mode.mdx | 44 +++++++++++++++++++++++++++ en/malachite/workspace-mode.mdx | 34 +++++++++++++++++++++ 4 files changed, 134 insertions(+), 5 deletions(-) create mode 100644 en/malachite/getting-started.mdx create mode 100644 en/malachite/repository-mode.mdx create mode 100644 en/malachite/workspace-mode.mdx diff --git a/en/malachite/common-features.mdx b/en/malachite/common-features.mdx index 4bfd7b6..389d247 100644 --- a/en/malachite/common-features.mdx +++ b/en/malachite/common-features.mdx @@ -107,7 +107,7 @@ The way this works is simple: I'm glad you asked! - If you want to clone a specific branch, simply use the `/` delimiter. To clone repository `foo` on branch `bar`, use `id:foo/bar`. -- If you want a specific package to build first, use instances of `!` to set priority. This is explained later in the [Repository Mode](REPOSITORY_MODE.md) page +- If you want a specific package to build first, use instances of `!` to set priority. This is explained later in the [Repository Mode](repository-mode) page The last `:` delimiter is entirely optional, and behaves differently depending on the mode: @@ -120,13 +120,13 @@ That's literally it! For mode-specific config, avert your eyes to the following links! -- [Workspace Mode](WORKSPACE_MODE.md) -- [Repository Mode](REPOSITORY_MODE.md) +- [Workspace Mode](workspace-mode) +- [Repository Mode](repository-mode) ## Examples -Functioning config examples for both modes are available in the [examples](../examples) directory! +Functioning config examples for both modes are available in the [examples](https://github.com/crystal-linux/malachite/tree/main/examples) directory! ## Usage -Alternatively, you can look at the [Usage](USAGE.md) guide! +Alternatively, you can look at the [Usage](detailed-usage) guide! diff --git a/en/malachite/getting-started.mdx b/en/malachite/getting-started.mdx new file mode 100644 index 0000000..1428ccc --- /dev/null +++ b/en/malachite/getting-started.mdx @@ -0,0 +1,51 @@ +--- +title: Getting Started With Malachite +weight: 20 +--- + +Baby's first Malachite repository! + +### What you need to know + +Malachite is: +- A pacman repository manager +- A workspace manager +- ~~Awesome~~ + +Malachite isn't: +- The end-all solution for all pacman repositories +- Perfect + + +### With that out of the way + +Hi! My name is Michal, and I wrote this tool pretty much on my own for [Crystal Linux](https://getcryst.al); +but it is not at all exclusive to Crystal. This tool should and will work on and for any pacman-based +distribution (so long as it packages all of Malachite's dependencies, of course). + +Throughout this tutorial, I'll explain each little feature of Malachite in what I hope to be bite-sized and +programmatic chunks. + +Without further ado, let's begin with the first, most important question: + + +### Modes + +What mode are you using malachite in? + +Currently, malachite supports 2 modes: + +#### Repository Mode +- Allows the user to configure and manage a remote (or local) pacman-based package repository +- Allows for customisability in repository name, signing preferences, signing key etc. +- Allows for basic levels of automation, by using features such as build_on_update + +#### Workspace Mode +- The most basic functionality of Malachite +- Just clones git directories into a "Workspace" directory for easier management +- Allows for basic pulling operations to keep your repositories up-to-date + +These modes essentially dictate everything about how Malachite functions, so much so that I now need to +split this page off before it gets too long! + +For more info, get started with the [Common Features](common-features) page! diff --git a/en/malachite/repository-mode.mdx b/en/malachite/repository-mode.mdx new file mode 100644 index 0000000..ce26bce --- /dev/null +++ b/en/malachite/repository-mode.mdx @@ -0,0 +1,44 @@ +--- +title: Repository Mode +--- + +PacManage your repositories in style! + +### Repository Config + +As opposed to the rather barren Workspace mode, the Repository mode config is rather fleshed out; +and we have a few options to choose from. + +Let's take an example section from a Repository mode config, + +```toml +[mode.repository] +name = "example" +build_on_update = true + +[mode.repository.signing] +enabled = true +key = "you@example.org" +on_gen = true +``` + +### Basic Repository Config + +To start with, there are 2 main config keys to Repository mode: +- `name`: Defines what pacman calls your repository. +- `build_on_update`: In conjunction with `smart_pull`, defines whether to rebuild packages automatically when an update is detected. + +### Signing + +Malachite also supports, and encourages, the signing of packages. +GPG Signing packages ensures that the user receives exactly what you packaged, without any chance of tampering. + +Calling back to the example above, we can see 3 config keys: + +- `enabled`: Defines whether to sign packages (heavily encouraged). +- `key`: Defines the GPG key ID to use for signing. +- `on_gen`: Defines whether to sign packages when they are built, or all at once on repository generation (this is also recommended). + +--- + +You can return to [Getting Started](getting-started) page here! diff --git a/en/malachite/workspace-mode.mdx b/en/malachite/workspace-mode.mdx new file mode 100644 index 0000000..3454c6c --- /dev/null +++ b/en/malachite/workspace-mode.mdx @@ -0,0 +1,34 @@ +--- +title: Workspace Mode +--- + +You'll never have to work(space) another day in your life! + +### Workspace Config + +Taking an example section from the Workspace mode config, + +```toml +[mode.workspace] +git_info = true +colorblind = true +``` + +Currently, Workspace mode only has 2 options, both pertaining to the display of information. (`mlc info`) + +The first key is `git_info`, which is a boolean value. If it is true, the git information will be displayed alongside repository information. + +This information will be formatted as so: `D Pl Ps ` + +The key for the values is as follows: +- D: Whether the repository is dirty or not (unstaged changes) +- Pl: Whether there are unpulled changes at the remote +- Ps: Whether there are unpushed changes in your local repository + +These will be typically displayed in either Green (Clean) or Red (Dirty) + +However, if `colorblind` is set to true, the colors will instead be set to Blue (Clean) or Dark Red (Dirty), to be more discernible to colorblind users. + +--- + +You can return to [Getting Started](getting-started) page here!