From 5226e1d625fafcc62ca828e2817ccd80ea802735 Mon Sep 17 00:00:00 2001 From: mrshmllow Date: Sun, 11 Sep 2022 16:27:45 +1000 Subject: [PATCH] Init --- Ameythest/usage.mdx | 0 Malachite/common_features.mdx | 131 ++++++++++++++++++++++++++++++++++ Malachite/usage.mdx | 35 +++++++++ getting_started.mdx | 5 ++ 4 files changed, 171 insertions(+) create mode 100644 Ameythest/usage.mdx create mode 100644 Malachite/common_features.mdx create mode 100644 Malachite/usage.mdx create mode 100644 getting_started.mdx diff --git a/Ameythest/usage.mdx b/Ameythest/usage.mdx new file mode 100644 index 0000000..e69de29 diff --git a/Malachite/common_features.mdx b/Malachite/common_features.mdx new file mode 100644 index 0000000..74a666a --- /dev/null +++ b/Malachite/common_features.mdx @@ -0,0 +1,131 @@ +--- +title: 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/Malachite/usage.mdx b/Malachite/usage.mdx new file mode 100644 index 0000000..4b333cc --- /dev/null +++ b/Malachite/usage.mdx @@ -0,0 +1,35 @@ +--- +title: 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/getting_started.mdx b/getting_started.mdx new file mode 100644 index 0000000..1ddb830 --- /dev/null +++ b/getting_started.mdx @@ -0,0 +1,5 @@ +--- +title: Getting Started +--- + +Welcome to the crystal docs!