Skip to content

Commit

Permalink
Init
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrshmllow
mrshmllow committed Sep 11, 2022
0 parents commit 5226e1d
Show file tree
Hide file tree
Showing 4 changed files with 171 additions and 0 deletions.
Empty file added Ameythest/usage.mdx
Empty file.
131 changes: 131 additions & 0 deletions Malachite/common_features.mdx
Original file line number Diff line number Diff line change
@@ -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!

35 changes: 35 additions & 0 deletions Malachite/usage.mdx
Original file line number Diff line number Diff line change
@@ -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 <package>` [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` |
5 changes: 5 additions & 0 deletions getting_started.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Getting Started
---

Welcome to the crystal docs!

0 comments on commit 5226e1d

Please sign in to comment.