docs: track full list of asdf dependencies

[jthegedus]

How can we improve the documentation?

It would be ideal to improve our list of dependencies and also capture the minimum supported versions.

Prior discussion #511

---

Dependencies list

Here is a non-comprehensive list of dependencies from a quick look through some code:

tool	min version	what makes that the min version	why/where do we use it?
git	1.7.7.2	git --work-tree	used in asdf plugin update with --git-dir to avoid cd. git -C is preferred but would require a later git version
git	1.8.5.6	git -C	used in tests in place of --git-dir+--work-tree
curl			used in plugin-test command
awk
grep
sed
tr
tail
head
cat

I am not sure if these tools are in the same class as the above. Should they be treated the same?

tool	min version	what makes that the min version	why/where do we use it?
read
printf
rm
command		command -v

Bash is almost certainly considered a dependency, but we will tackle that in another Issue.

Thoughts

Is it even possible to list all min versions of tools which are different implementations of the same tool for different OSs? Eg: BSD vs GNU grep. Are the versions tracked the same? One assumes not as they could differ in minor/patch releases due to non-breaking changes and bugfixes, right? 🤔

Banned Commands

We have already banned some commands, or even just flags on commands because they are not common across most platforms. See - https://github.com/asdf-vm/asdf/blob/master/test/banned_commands.bats

Potential reduction

I am sure we can reduce this list.

curl is used in plugin-test to fetch the Rate Limit dynamically to an error message. We can probably get rid of it as the users who see this branch of code is definitely a single digit number.

Why raise this issue

• it would be good to know
• we already ban certain tools & flags which is some form of tracking
• we don't list the actual dependencies in our documentation site. curl is listed but technically not used by asdf core
• we don't list minimum versions
• we get into conversations about this in various issues:
  • Clean up dependencies in documentation #511
  • feat: added gitlab support, simplified version sorting with ls-remote asdf-plugin-template#58

Todo

What can we do to resolve this issue:

• identify the dependencies (asdf core & tests)
• identify the minimum versions of each dependency (for asdf core & tests)
• capture in our documentation
• identify opportunities to reduce our dependencies

We will almost certainly get this wrong in some capacity, but any % of correctness is better than what we currently have.

How can you help?

Comment if you determine new tools or minimum versions used in the codebase.

[stephanGarland]

read and printf are shell built-ins. read differs greatly between shells, though, so if there's ever a desire to make this support other shells, that would need to be addressed.

The following are part of either GNU coreutils, or part of the base for BSD and BSD-like systems (e.g. MacOS). If someone is missing any of these and wants to use asdf, they are on a very bespoke system and they will know how to work around it.

cat, head, rm, tail, tr

The other three - awk, grep, sed - are all incredibly common, but the main issue comes down to the differences between distributions. GNU and BSD versions of all of these tools have some quirky differences; e.g BSD sed requires the -i flag to have a string given as a filename for the backup, even if the string is empty. Of the three, I think awk is the most portable in terms of its regex and filtering capabilities.

Also worth noting that if it is decided to require bash >= 4, tr can be dropped entirely in favor of built-in parameter modification, and you get a speed boost out of it as well.

[jthegedus]

Mentioned in #1436 we are likely going to [have to] support Bash 3.2 because of macOS.

[hyperupcall]

In my shell scripts, I only have a minimum Bash version, and list the external scripts I use that are not strictly POSIX compliance. In my opinion, it's the best way to show necessary dependencies without having too long a list.

In non-application cases, I list all non builtins, but I don't think that's applicable here.

So judging from that list, I think it's important that we mention a minimum Git and cURL version. I haven't checked the flags for all the other commands, so I'm not sure if they are fully POSIX compliant (hopefully they are). Definitely skip over the builtins though, not necessary because they are covered by the minimum Bash version.

[hyperupcall]

Another dependency (development): Bats

Bats now has a bats_require_minimum_version function to enforce this - but it was added quite recenctly. (there is a backporting mechanism, but requires some setup)

[MetricMike]

On stephanGarland's comment above: #1435 (comment)

asdf-awscli ran into a problem with cp - macOS comes with BSD cp, Linux flavors come with varying versions of GNU cp (usually 8), and it's not uncommon for folks to install the latest coreutils package (v9) via homebrew. Unfortunately, they all have different behavior for cp -r DIRECTORY1 DIRECTORY2. Switching to cp -LR and ensuring DIRECTORY2 doesn't exist yet appears consistent across all 3 versions and OS platforms.

An alternative that I didn't pursue was only using system-provided utils (/bin/cp vs cp), but that feels like a worse solution that limits coverage to what github action runners I use. Does asdf have a preference/tips for how to guard against cross-platform issues like this? Neither avoiding coreutils or trying 20 different option flags to find the ones that perform the same seem ideal.