search

twpayne / chezmoi

Manage your dotfiles across multiple diverse machines, securely.
https://www.chezmoi.io/
MIT License
13.36k stars 493 forks source link

Improve documentation about app binary download #3562

Closed infused-kim closed 8 months ago

infused-kim commented 9 months ago

Hi,

Problem description

One of my favorite features of chezmoi is the chezmoi external function. For me, it solves the "Don't bother learning anything except for vim, because only vim is available everywhere" problem.

For the longest time I had a great terminal setup on my local machine with modern replacements for common terminal commands like eza, fd, etc.

But as soon as I SSHed anywhere else, it was back to 1995. On some of these machines I also didn't have root or was not comfortable installing random, unrelated packages globally.

At some point I even tried using nix home manager... But that was a huge pain in the ass that just wasn't worth it :)

When I started looking for a dotfiles manager, this was a must-have feature. But initially it seemed like there was no function for this in chezmoi.

Fortunately, I found a github issue that described how to do it using the chezmoi external feature and it solved the problem absolutely perfectly.

While learning how to use chezmoi I also looked through most of the .dotfile repos using chezmoi on github and saw almost no repos that were using this feature.

Even though it's an extremely useful feature, it seems to be very underused.

What I propose

I think it would be great to promote it more on the website and documentation.

Homepage

Currently the homepage describes chezmoi like this:

chezmoi provides many features beyond symlinking or using a bare git repo including: templates (to handle small differences between machines), password manager support (to store your secrets securely), importing files from archives (great for shell and editor plugins), full file encryption (using gpg or age), and running scripts (to handle everything else).

I suggest to add an additional sentence like:

Additionally, it allows you to download files from external locations, such as shell plugins or even pre-compiled, cross-platform binaries of command line tools. This allows your entire shell setup to be completely portable across any machine or server you are using (even if you don't have root access to install programs there).

Include dotfiles from elsewhere page

Here I would add a section Include pre-compiled command line tools with similar copy as above and perhaps the example config file below.

Example config

I think a lot of people use a similar set of tools in their "modern shell stack", such as eza, bat, fd, etc. It might make sense to maintain an example config with the right settings to download all of those tools.

Here is what I am currently using as a starting point:

#
# Settings
#

{{- $refreshPeriod := "168h" }}

#
# Prepare binary arch strings
#

#
# $arch_1:
# - aarch64-apple-darwin, x86_64-apple-darwin
# - aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu
#
# $arch_2 (No arm for macOS):
# - x86_64-apple-darwin, x86_64-apple-darwin
# - aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu
#
# $arch_3 (linux-musl version):
# - aarch64-apple-darwin, x86_64-apple-darwin
# - aarch64-unknown-linux-musl, x86_64-unknown-linux-musl
#
# $arch_4 (No arm for macOS, linux-musl version):
# - x86_64-apple-darwin, x86_64-apple-darwin
# - aarch64-unknown-linux-musl, x86_64-unknown-linux-musl
#
# $arch_5 (Simple names):
# - aarch64-macos, x86_64-macos
# - aarch64-linux, x86_64-linux
#

{{- $arch_1 := "none" }}
{{- $arch_2 := "none" }}
{{- $arch_3 := "none" }}
{{- $arch_4 := "none" }}
{{- $arch_5 := "none" }}

{{ if eq .chezmoi.os "darwin" }}
    {{ if eq .chezmoi.arch "arm64" }}
        {{ $arch_1 = "aarch64-apple-darwin" }}
        {{ $arch_2 = "x86_64-apple-darwin" }}
        {{ $arch_3 = "aarch64-apple-darwin" }}
        {{ $arch_4 = "x86_64-apple-darwin" }}
        {{ $arch_5 = "aarch64-macos" }}
    {{ else }}
        {{ $arch_1 = "x86_64-apple-darwin" }}
        {{ $arch_2 = "x86_64-apple-darwin" }}
        {{ $arch_3 = "x86_64-apple-darwin" }}
        {{ $arch_4 = "x86_64-apple-darwin" }}
        {{ $arch_5 = "x86_64-macos" }}
    {{ end }}
{{ else if eq .chezmoi.os "linux" }}
    {{ if eq .chezmoi.arch "arm64" }}
        {{ $arch_1 = "aarch64-unknown-linux-gnu" }}
        {{ $arch_2 = "aarch64-unknown-linux-gnu" }}
        {{ $arch_3 = "aarch64-unknown-linux-musl" }}
        {{ $arch_4 = "aarch64-unknown-linux-musl" }}
        {{ $arch_5 = "aarch64-linux" }}
    {{ else }}
        {{- $arch_1 = "x86_64-unknown-linux-gnu" }}
        {{- $arch_2 = "x86_64-unknown-linux-gnu" }}
        {{- $arch_3 = "x86_64-unknown-linux-musl" }}
        {{- $arch_4 = "x86_64-unknown-linux-musl" }}
        {{- $arch_5 = "x86_64-linux" }}
    {{ end }}
{{ end }}

#
# Prepare other variables
#

{{- $githubPath := "none"}}
{{- $versionTag := "none" }}
{{- $os := "none" }}

#
# Binary Settings
#

[".local/bin/hx"]
    {{- $githubPath := "helix-editor/helix"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    stripComponents = 1
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/helix-{{ $versionTag }}-{{ $arch_5 }}.tar.xz"
    path = "hx"

[".local/bin/bat"]
    {{- $githubPath := "sharkdp/bat"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    executable = true
    stripComponents = 1
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/bat-{{ $versionTag }}-{{ $arch_2 }}.tar.gz"
    path = "bat"

{{ if eq .chezmoi.os "darwin" }}

# There are no eza builds for macOS. So we use exa, but ideally eza can be installed from brew.

[".local/bin/exa"]
    {{- $githubPath := "ogham/exa"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/exa-macos-x86_64-{{ $versionTag }}.zip"
    path = "bin/exa"

{{ else }}

[".local/bin/eza"]
    {{- $githubPath := "eza-community/eza"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/eza_{{ $arch_1 }}.zip"
    path = "eza"

{{ end }}

[".local/bin/delta"]
    {{- $githubPath := "dandavison/delta"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    stripComponents = 1
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/delta-{{ $versionTag }}-{{ $arch_1 }}.tar.gz"
    path = "delta"

[".local/bin/fd"]
    {{- $githubPath := "sharkdp/fd"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    stripComponents = 1
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/fd-{{ $versionTag }}-{{ $arch_2 }}.tar.gz"
    path = "fd"

[".local/bin/aichat"]
    {{- $githubPath := "sigoden/aichat"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "archive-file"
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/aichat-{{ $versionTag }}-{{ $arch_3 }}.tar.gz"
    path = "aichat"

[".local/bin/yq"]
    {{- $githubPath := "mikefarah/yq"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

    type = "file"
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/yq_{{ .chezmoi.os }}_{{ .chezmoi.arch }}"

[".local/bin/jq"]
    {{- $githubPath := "jqlang/jq"}}
    {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}
    {{- $os = "unknown" }}
    {{ if eq .chezmoi.os "darwin" }}
        {{ $os = "macos" }}
    {{ else }}
        {{- $os = .chezmoi.os }}
    {{ end }}

    type = "file"
    executable = true
    refreshPeriod = "{{ $refreshPeriod }}"

    url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/jq-{{ $os }}-{{ .chezmoi.arch }}"

{{ if eq .chezmoi.os "linux" }}
    # These are utilities that don't provide packages for macOS and therefore
    # should be installed through brew

    [".local/bin/broot"]
        type = "file"
        executable = true
        refreshPeriod = "{{ $refreshPeriod }}"

        url = "https://dystroy.org/broot/download/{{ $arch_1 }}/broot"

    {{ if eq .chezmoi.arch "amd64" }}

        [".local/bin/fish"]
            {{- $githubPath := "mliszcz/fish-shell"}}
            {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

            type = "file"
            executable = true
            refreshPeriod = "{{ $refreshPeriod }}"

            url = "https://github.com/{{ $githubPath }}/releases/download/{{ $versionTag }}/{{ $versionTag }}.AppImage"

        [".local/bin/chafa"]
            {{- $githubPath := "hpjansson/chafa"}}
            {{- $versionTag = (gitHubLatestRelease $githubPath).TagName }}

            type = "archive-file"
            stripComponents = 1
            executable = true
            refreshPeriod = "{{ $refreshPeriod }}"

            url = "https://hpjansson.org/chafa/releases/static/chafa-{{ $versionTag }}-1-x86_64-linux-gnu.tar.gz"
            path = "chafa"

    {{ end }}
{{ end }}
halostatue commented 9 months ago

I use at least some of these, but I have shifted to installing them using MacPorts on macOS (I previously installed them with cargo binstall). I'm not sure that these are common enough — and more importantly portable enough (chezmoi is used on Windows) — to modify the documentation.

I do think that this list would make a nice Show & Tell post where people could pick and choose and add other variants as they wish.

What might be worth adding to the documentation is a section around the FAQ to "Interesting Ideas" that links to both the overall Show & Tell discussion, but perhaps adds links to a few interesting discussions, possibly including this one.

halostatue commented 9 months ago

It's also worth mentioning that there are other tools that may be more appropriate for this particular task:

I have not used any of these at this point, so I cannot recommend any one, but they are all focused on local installation of GitHub-release based binaries.

infused-kim commented 8 months ago

It's also worth mentioning that there are other tools that may be more appropriate for this particular task:

I have not used any of these at this point, so I cannot recommend any one, but they are all focused on local installation of GitHub-release based binaries.

Thank you! I haven't heard of these and will make sure to check them out.

twpayne commented 8 months ago

Hopefully this is now resolved. Please re-open if needed.