Documentation time!

main
Michal 2 years ago
parent 5169e23790
commit 17b37aa7c8

@ -0,0 +1,123 @@
# Common Features Between Modes
As[mode]us, shared of between uh... repositories... or something.
### What you need to know
Malachite is fairly fleshed out in Repository mode, and not so much in Workspace mode.
This isn't of course because I'm lazy and hate Workspace mode or anything, there's just not
a whole lot *to* add.
Without further ado, let's take a look at this example config file.
```toml
# mlc.toml
[base]
mode = "workspace"
smart_pull = true
[mode.repository]
name = ""
build_on_update = false
[mode.repository.signing]
enabled = false
key = ""
on_gen = false
[mode.workspace]
[repositories]
name = [
"1::foo",
"1::bar"
"2::baz",
"2::qux",
]
urls = [
"https://example.org/%repo%.git",
"https://example.org/other/%repo%.git",
]
```
Now this is going to look really confusing at first, but bear with me.
In this document we'll cover only what is required to know for **both** modes.
More specialised tutorials will be linked for each mode at the bottom of this page.
Let's start with the base(ics).
### Base Config
The base config defines a few common parameters between all the Malachite modes.
```toml
[base]
mode = "workspace"
smart_pull = true
```
In this snippet, we define `mode` to be `"workspace"`.
`base.mode` in Malachite can only ever be one of `"workspace"` or `"repository"`, and defines, drumroll...
The mode in which it operates.
If it is set to anything but those 2 modes, it crashes.
Also defined in this snippet is `smart_pull`, which controls whether or not to pull... smartly.
What that actually means is that instead of just performing a simple `git pull` in each repository, Malachite
will:
- First run `git remote update` to fetch new remotes from origin
- Then run `git status` and parse the output to see if the current branch is behind
- If the current branch is behind, it runs a regular `git pull`, which will take advantage of the remotes
already being updated.
Theoretically, this only actually speeds things up by a minute amount (think milliseconds, really). Where this feature shines however is in repository mode,
where it enables helpful automation features such as `build_on_update`.
Either way, it's recommended to keep this enabled for the slight speedup, and only disable it if it causes issues.
I've never personally had issues with it in the past, but who knows what could happen. This is Git we're talking about.
### Repositories Config
The repositories config is realistically what makes Malachite churn repo butter internally. It's the whole
purpose of what it does, and because of that we've tried to come up with a neat little system so as to help
facilitate many packages without having to type each url out a million times.
```toml
[repositories]
name = [
"1::foo",
"1::bar"
"2::baz",
"2::qux",
]
urls = [
"https://example.org/%repo%.git",
"https://example.org/other/%repo%.git",
]
```
The way this works is simple.
We have 2 urls in the `repositories.urls` key.
Each `name` in the `repositories.name` key is prefixed with an index.
If the number is `1`, it'll insert the name into the `1`st URL.
Specifically, in the repo's URL, it'll insert the defined `name` in place of the `%repo%` substring.
That's literally it!
### Mode-Specific Config
For mode-specific config, avert your eyes to the following links!
- [Workspace Mode](WORKSPACE_MODE.md)
- [Repository Mode](REPOSITORY_MODE.md)

@ -0,0 +1,47 @@
# Getting Started With Malachite
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, 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.md) page!
Loading…
Cancel
Save