upstream-rs 2.0.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
97
98
99
100
101

# Building From Source

Use `upstream build` when a project publishes source releases but does not provide a suitable prebuilt artifact for your system.

```bash
upstream build <repo-or-url> <name>
```

The canonical form is `<repo-or-url> <name>`. For git repositories, upstream can fall back to the repository name when `<name>` is omitted.

## Supported Profiles

Upstream can auto-detect or explicitly use these build profiles:

| Profile | Detection | Default output expectation |
| --- | --- | --- |
| `rust` | `Cargo.toml` | `target/release/<name>` |
| `dotnet` | `.sln` or `.csproj` | `.upstream-build/publish/<name>` |
| `go` | `go.mod` | `.upstream-build/<name>` |
| `zig` | `build.zig` | `zig-out/bin/<name>` |
| `cmake` | `CMakeLists.txt` | `.upstream-build/cmake/<name>` |

Force a profile when detection is ambiguous:

```bash
upstream build BurntSushi/ripgrep rg --build-profile rust
```

## Tags, Branches, and Channels

Build a release tag:

```bash
upstream build owner/repo app --tag v1.2.3
```

Build a branch head:

```bash
upstream build owner/repo app --branch main
```

Without `--tag` or `--branch`, Upstream resolves the latest release for the selected channel.

## Build Cache

Git source builds use cached workspaces under:

```text
$HOME/.upstream/cache/build/
```

When upgrading or rebuilding a git source package, Upstream fetches the cached repository, checks out the requested branch or release tag, pulls changes when appropriate, and rebuilds in place. This lets project build systems reuse existing build artifacts when they support incremental rebuilds.

If a source is only available as an archive, Upstream falls back to a cached source-archive workspace under:

```text
$HOME/.upstream/cache/source-archives/
```

Archive cache refreshes update source-controlled files while preserving unowned build output where possible.

## Build Scripts

After the profile build succeeds, Upstream looks for project-provided install/upgrade scripts in the repository root or `scripts/` directory.

Install builds look for:

```text
install.sh
install.bash
install.ps1
```

Upgrade/rebuild flows prefer:

```text
upgrade.sh
upgrade.bash
upgrade.ps1
```

If no upgrade script exists, upgrade flows fall back to install scripts. Scripts are shown for review and require confirmation before execution unless `--yes` is used.

Unix shell scripts must include a shebang. PowerShell scripts run through `pwsh` when selected.

## Installation After Build

The built artifact is staged and then installed through the same package installer used for downloaded artifacts. Build-installed packages are stored with source metadata so `upgrade` and `reinstall` can rebuild them later.

Use `--desktop` for GUI apps:

```bash
upstream build owner/repo app --desktop
```

If desktop integration fails, Upstream rolls back the partial install.

## Limitations

Upstream does not manage language-specific dependencies for you. The relevant build toolchain and project dependencies must be available in the environment. If a project does not build cleanly with one of the supported profiles, install from a release asset instead.