`install tt` may be confusing for a user without prepared Go environment

I decided to try a new feature introduced in the PR #664. To check that it works fine, I used a clean ubuntu:22.04 container environment.

tt install tt pr/664
   • Searching in pull-requests...
   • Checking existing...     
   • Installing tt=pr/664     
   • Checking dependencies... 
   ⨯ The operation requires some dependencies.
Missing packages:  mage
You can install them by running command:
install from sources: mage
Usage: tt install -f if you already have those packages installed

The message is clear. So I go to the Mage project website for an installation procedure.

[install] Using Go Modules (Recommended)

git clone https://github.com/magefile/mage
cd mage
go run bootstrap.go

Using GOPATH

go get -u -d github.com/magefile/mage
cd $GOPATH/src/github.com/magefile/mage
go run bootstrap.go

I need to install Go first. I can use either apt (it has Go 1.18, which should be enough for tt) or Go website installation guide for tar.gz.

Remove any previous Go installation by deleting the /usr/local/go folder (if it exists), then extract the archive you just downloaded into /usr/local, creating a fresh Go tree in /usr/local/go:

  $ rm -rf /usr/local/go && tar -C /usr/local -xzf go1.21.3.linux-amd64.tar.gz

(You may need to run the command as root or through sudo).

Do not untar the archive into an existing /usr/local/go tree. This is known to produce broken Go installations.
Add /usr/local/go/bin to the PATH environment variable.

You can do this by adding the following line to your $HOME/.profile or /etc/profile (for a system-wide installation):

      export PATH=$PATH:/usr/local/go/bin

Note: Changes made to a profile file may not apply until the next time you log into your computer. To apply the changes immediately, just run the shell commands directly or execute them from the profile using a command such as source $HOME/.profile.
Verify that you've installed Go by opening a command prompt and typing the following command:

      $ go version

Confirm that the command prints the installed version of Go.

After installing Go with any method and running any of two mage install guides, I get the following result.

mage --version
bash: mage: command not found

As a developer with some Go experience, I understand that the issue is related to additional go paths setup. As a not very well-experienced Go developer, each time I forget what exact actions I need to do to set up my path. Go installation guide and Mage installation guide does not cover it in any way. The middle section of "writing your first Go program" guide actually does.

export PATH=$PATH:$(dirname $(go list -f '{{.Target}}' .))

So, setting up mage (thus, using tt install tt) for a Linux user may be confusing if one haven't got Go modules path set up yet. To improve this experience, we may cover building mage from sources in our documentation or try to contribute to mage installation guide.

Start by reproducing tt install tt pr/664 in a clean ubuntu:22.04 environment and reviewing the Mage installation guidance linked in the issue. The work is complete when a user without a prepared Go environment can follow the documented setup and successfully run mage --version, or the command clearly explains the required setup.