Add git deps with gleam add

[seafoamteal]

Right now, to add a dependency from Git, you have to edit your gleam.toml file. This will invariably involve having to look up the syntax either online or with gleam deps help 😅 . Also, it's just less ergonomic than a simple command in the terminal. I think it would be better if you could use gleam add as usual. Some brief discussion on Discord seems to suggest that other people think so too.

What would this look like?

The most familiar UX would be that gleam add accepts any URL you would normally pass to git clone, with an --ref / -r flag. This corresponds pretty directly to the current gleam.toml syntax and the dependency resolution code in the Gleam build tool.

gleam add https://github.com/lustre-labs/ui --ref headless-redux-redux

gleam add https://tangled.org/haripm.com/snowball_stemmer -r a2dc4eff

gleam add ssh://user@host:/some/path --ref v1.0.1

We unfortunately wouldn't be able to use @ to separate the URL and the ref like we do for Hex packages, because @ is a valid character in Git branches and tags. I considered using a : instead, like how Docker does image:tag but having different separators for Hex and Git packages will probably cause confusion.

We could potentially make the --ref flag optional and take it to mean that the user wants the tip of the default branch if left unspecified.

Making this a discussion because it feels like it calls for more design work than a regular issue, but if/when this is approved, I'd be more than happy to work on it!

[GearsDatapacks]

We also couldn't use : to separate them because of https:, etc.

[lpil]

What do other package managers do? It would be useful to see the equivalent APIs in all others that we are aware of.

[seafoamteal]

Just for some extra information, this is how Bun does it

bun add git+https://github.com/lodash/lodash.git
bun add git+ssh://github.com/lodash/lodash.git#4.17.21
bun add git@github.com:lodash/lodash.git
bun add github:colinhacks/zod

So they also use the git+ protocols, but use a pound sign/octothorpe to separate the URL and version. It looks like npm does the same thing, and they have a proper reference in their docs:

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

is one of git, git+ssh, git+http, git+https, or git+file

It seems protocol is required with npm. Here is the link if you want to read further.

I also looked up how Ruby does it with Bundler, but apparently they don't do it via CLI; you have to edit the Gemfile. Similarly, Conan (C package manager) also requires you to modify the config file.

---

All that said, I also agree that the cargo or uv UXs seem nicer. I don't really have on opinion on either, so I'll just agree with Louis that the cargo way is the better one. I also agree that the package name and ref arguments should be optional.

I suppose we don't want to disambiguate between branch, tag, and rev, seeing as gleam.toml doesn't currently? I don't actually know the reason why cargo and uv do this: Git is capable of figuring it out.

[lpil]

Just ref seems fine to me 👍

[seafoamteal]

Cool! Am I okay to start working on this then?

[lpil]

I think we have something here. Could you make an issue with the details for the flag based API first please? 🙏

[seafoamteal]

Of course! Will get around to it this weekend.