upstream-rs 2.4.0

Fetch package updates directly from the source.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# Installation and Paths

Upstream is a rootless package manager. It installs packages and metadata under the current user's home/config directories and does not require system package-manager privileges.

## Install Methods

Recommended bootstrap scripts:

```bash
# Linux
curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.bash | bash

# macOS
curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.zsh | zsh

# Windows PowerShell
iwr -useb https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.ps1 | iex
```

Cargo install:

```bash
cargo install upstream-rs
```

Cargo installs do not participate in Upstream self-updates through `upstream upgrade`.

Manual install:

1. Download an `upstream` release artifact from the GitHub releases page.
2. Put the binary somewhere on `PATH`.
3. Run `upstream hooks init`.

## Shell Integration

Initialize shell integration after installing the binary:

```bash
upstream hooks init
```

This creates Upstream-managed directories and config files, then adds shell hooks so installed package symlinks are on `PATH`.

Useful hook commands:

```bash
upstream hooks check
upstream hooks clean
upstream --yes hooks purge
```

- `hooks check` verifies directories, metadata files, and shell profile integration.
- `hooks clean` removes shell profile hooks.
- `hooks purge` removes hooks and deletes local Upstream data.

## On-Disk Layout

Upstream stores data in user-owned locations:

| Path | Purpose |
| --- | --- |
| `$XDG_CONFIG_HOME/upstream/config.toml` | Main configuration file |
| `$HOME/.upstream/migration.json` | Root layout manifest used by init, doctor, and migration |
| `$HOME/.upstream/metadata/packages.json` | Installed package metadata |
| `$HOME/.upstream/metadata/metadata.json` | Sidecar metadata such as pin reasons |
| `$HOME/.upstream/metadata/trust.json` | Trusted minisign and cosign public keys |
| `$HOME/.upstream/metadata/transactions.json` | Mutating package transaction history |
| `$HOME/.upstream/metadata/paths.sh` | POSIX/fish PATH export managed by hooks |
| `$HOME/.upstream/metadata/paths.nu` | Nushell PATH export managed by hooks |
| `$HOME/.upstream/packages/binaries/` | Installed binary artifacts |
| `$HOME/.upstream/packages/appimages/` | Installed AppImage artifacts |
| `$HOME/.upstream/packages/archives/` | Extracted archive installs |
| `$HOME/.upstream/cache/` | Reusable package cache data |
| `$HOME/.upstream/cache/build/` | Cached git workspaces for source builds |
| `$HOME/.upstream/cache/source-archives/` | Cached source archive workspaces |
| `$HOME/.upstream/cache/completions/` | Cached package completion scripts |
| `$HOME/.upstream/tmp/` | Temporary staging for package operations |
| `$HOME/.upstream/symlinks/` | Runtime command links |
| `$HOME/.upstream/icons/` | Stored desktop icons |
| `$HOME/.upstream/rollback/` | Rollback artifacts |

Desktop entries are written to `$HOME/.local/share/applications` on Linux. Shell completions are cached under `$HOME/.upstream/cache/completions/<package>/` and copied into shell-specific user completion directories when supported.

## Migration

After upgrading across breaking layout changes, run:

```bash
upstream migrate
```

`doctor` detects common legacy layouts and recommends `migrate` when local data appears to use an older format.

## Updating Upstream Itself

The bootstrap scripts install Upstream through Upstream after the binary is available. Once tracked as a package, `upstream upgrade upstream` or plain `upstream upgrade` can update it like other managed packages.