From 5f2dcb163f08940ea126da48ac41cc3d9060002c Mon Sep 17 00:00:00 2001 From: Michal S Date: Tue, 27 Sep 2022 23:58:49 +0100 Subject: [PATCH] Moved docs --- docs/COMMON_FEATURES.md | 128 ---------------------------------------- docs/GETTING_STARTED.md | 47 --------------- docs/REPOSITORY_MODE.md | 41 ------------- docs/USAGE.md | 32 ---------- docs/WORKSPACE_MODE.md | 31 ---------- 5 files changed, 279 deletions(-) delete mode 100644 docs/COMMON_FEATURES.md delete mode 100644 docs/GETTING_STARTED.md delete mode 100644 docs/REPOSITORY_MODE.md delete mode 100644 docs/USAGE.md delete mode 100644 docs/WORKSPACE_MODE.md diff --git a/docs/COMMON_FEATURES.md b/docs/COMMON_FEATURES.md deleted file mode 100644 index 2bf3d53..0000000 --- a/docs/COMMON_FEATURES.md +++ /dev/null @@ -1,128 +0,0 @@ -# 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 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.workspace] -git_info = true -colorblind = true - -[repositories] -repos = [ - "foo:repo1:2", - "foo:repo2/testing", - "bar:baz!", - "bar:qux/testing!:1", -] - -[repositories.urls] -foo = "https://example.org/{}.git" -bar = "https://example.org/other/{}.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 specialized 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 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`. - -Regardless, it's recommended to keep this enabled for the slight speed-up, 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 to help -facilitate many packages without having to type each URL out a million times. - -```toml -[repositories] -repos = [ - "foo:repo1:2", - "foo:repo2/testing", - "bar:baz!", - "bar:qux/testing!:1", -] - -[repositories.urls] -foo = "https://example.org/{}.git" -bar = "https://example.org/other/{}.git" -``` - -The way this works is simple: -- We have 2 URLs in the `repositories.urls` key. -- Each `repo` in the `repositories.repos` key is prefixed with an identifier. -- If the number is `foo`, it'll insert the URL with the id `foo`. - - Specifically, in the URL, it'll insert the defined `repo`'s name in place of the `%repo%` substring. - -#### Hang on, what are the special symbols???? - -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 - -The last `:` delimiter is entirely optional, and behaves differently depending on the mode: -- In Repository mode, it defines the desired commit hash/rev/tag to checkout on repository clone -- In Workspace mode, it defines the desired depth to clone the repository, useful with large git repositories, such as `nixpkgs`. - -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) - -### Examples - -Functioning config examples for both modes are available in the [examples](../examples) directory! - -### Usage - -Alternatively, you can look at the [Usage](USAGE.md) guide! - diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md deleted file mode 100644 index 6bd3462..0000000 --- a/docs/GETTING_STARTED.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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, 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.md) page! diff --git a/docs/REPOSITORY_MODE.md b/docs/REPOSITORY_MODE.md deleted file mode 100644 index 60a580c..0000000 --- a/docs/REPOSITORY_MODE.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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.md) page here! diff --git a/docs/USAGE.md b/docs/USAGE.md deleted file mode 100644 index 549e6a5..0000000 --- a/docs/USAGE.md +++ /dev/null @@ -1,32 +0,0 @@ -# Detailed Usage -Work it harder, make it better! - -### Global Flags - -| Flag | Description | -|-------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `--verbose`, `-v` | Prints lots of debug information to `stderr`. If something doesn't go right, sending us the output with this enabled will help greatly | -| `--exclude`, `-x` | Excludes the supplied package from the current operation. Can be used multiple times. | - -### Basic Commands - -| Action | Command | Extra Flags | -|-----------------------------------------------------------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------------| -| Build a package/packages. | `mlc build ` [all if left empty] | `--no-regen`: Doesn't regenerate repository after build | -| Generate pacman repository | `mlc repo-gen` | | -| Update local repos/PKGBUILDs | `mlc pull/update` [all if left empty] | `--no-regen`: If `mode.repository.build_on_update` is `true`, Do not regenerate repository after package rebuild | -| Create and/or open config file | `mlc conf` | | -| Initialises repo/workspace based on config in mlc.toml | `mlc clone/init` | | -| Displays an info panel/overview of the current repo | `mlc info/status` | | -| Resets Malachite repository by deleting all directories, omitting `mlc.toml` and `.git` | `mlc clean/reset` | `--force`: Remove dirty directories (unstaged, untracked, etc) | - -### Exit Codes - -| AppExitCode (named Enum) | Exit code (i32) | Error Description | -|--------------------------|-----------------|--------------------------------------------------------------------------------------------------------| -| `RunAsRoot` | `1` | Malachite was run as root. This is highly discouraged. So highly, in fact, that it will refuse to run. | -| `PkgsNotFound` | `2` | No packages were specified/found for the desired operation | -| `DirNotEmpty` | `3` | The creation of a Malachite repository was attempted in a non-empty directory | -| `ConfigParseError` | `4` | The config file could not be parsed | -| `RepoParseError` | `5` | The repository info could not be parsed | -| `RepoNotClean` | `6` | The git repository is not clean and cannot be removed without `--force` | diff --git a/docs/WORKSPACE_MODE.md b/docs/WORKSPACE_MODE.md deleted file mode 100644 index 14efb54..0000000 --- a/docs/WORKSPACE_MODE.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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.md) page here!