isacikgoz / tldr

fast and interactive tldr client written with go

tldr++

Community driven man pages improved with smart user interaction. tldr++ seperates itself from any other tldr client with convenient user guidance feature.

Features

• Fully Interactive (fill the command arguments easily)
• Search from commands to find your desired command (exact + fuzzy search)
• Smart file suggestions (further suggestions will be added)
• Simple implementation
• One of the fastest clients, even fastest (see Benchmarks)
• Easy to install. Supports all mainstream OS and platforms (Linux, MacOS, Windows (v1.0 excluded for a while)(arm, x86)
• Pure-go (even contains built-in git)

Installation

Refer to Release Page for binaries.

Or, you can build from source: (min. go 1.18 compiler is recommended)

go install github.com/isacikgoz/tldr/cmd/tldr@latest

macOS using brew

brew install isacikgoz/taps/tldr

Windows using scoop

This is maintained by community and the version is v0.6.1. (v1.0.0 does not have Windows support yet)

scoop install tldr

Use for different OS

You can use tldr++ for another OS by setting TLDR_OS envrionment to your desired OS such as linux, windows, osx etc.

Let's say you want to set it to Linux run the following command:

export TLDR_OS=linux

To make it permenant, you can add the line above to your shell rc file (e.g. bashrc, zshrc etc.)

Credits

• tldr-pages
• go-prompt
• fuzzy
• go-git
• kingpin
• color

tldr's Issues

WSL?

I'm using WSL on Windows 10 (hopefully soon to be using WSL2). The PC's processor is an Intel i7-7820HQ @ 2.90GHz. The flavor of Linux I'm currently running in WSL is Pengwin. I'm pretty sure it's Debian-based since it uses apt.

It doesn't seem like any of the release versions work for one reason or another. Which one should I get and how should it be installed?

[Request] Adding `q` as an exit option, alongside ctrl + c?

Is there any downside to adding q as an exit option, alongside ctrl + c? It feels natural for a TUI, and it is unused for anything else at the moment as far as I can see. Also, ctrl + c works perfect, but still feels like a dirty way to exit a program.
If such an option would be useful, I can take a crack at implementing it, even though I do not know go yet (could be a nice first pull request task).

Unexpected Escape Sequence: ['\x1b' 'O']%

Any of the navigation keys will give me that message:Unexpected Escape Sequence: ['\x1b' 'O']% .
I've reinstalled it and tried it on two shells(bash, zsh) and terminal (tilix, urxvt, xfce4-terminal). I only get this escape message on tldr++.

I ran strace and this is what I got for the last lines:

ioctl(0, TCGETS, {B38400 opost isig icanon echo ...}) = 0
ioctl(0, SNDCTL_TMR_START or TCSETS, {B38400 opost -isig -icanon -echo ...}) = 0
write(1, "\33[?25l", 6) = 6
read(0, "\33OB", 4096) = 3
futex(0xf724f0, FUTEX_WAKE_PRIVATE, 1) = 1
futex(0xf723f0, FUTEX_WAKE_PRIVATE, 1) = 1
write(1, "\33[?25h", 6) = 6
ioctl(0, SNDCTL_TMR_START or TCSETS, {B38400 opost isig icanon echo ...}) = 0
write(1, "\33[?7h", 5) = 5
write(1, "Unexpected Escape Sequence: ['\x"..., 40Unexpected Escape Sequence: ['\x1b' 'O']) = 40
exit_group(0) = ?
+++ exited with 0 +++

Is there an option to customize the colors?

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

No response

Expected Behavior

No response

Steps To Reproduce

No response

Environment

- OS: mac
- Terminal emulator: kitty
- Go version: 1.18

Anything else?

No response

Add commands to shell history

So I can go back and correct something, or use something like sudo !!.
In zsh, this works through print -s, dunno how it is in other shells.

go get fails: does not contain package github.com/isacikgoz/tldr/cmd/tldr

I'm unable to go get the package due to the following error:

$ go get github.com/isacikgoz/tldr/cmd/tldr
go get: module github.com/isacikgoz/tldr@upgrade found (v0.6.1), but does not contain package github.com/isacikgoz/tldr/cmd/tldr

go get fails due to go-git.v4

When I tried to install using go get github.com/isacikgoz/tldr/cmd/tldr it failed with the error message

# gopkg.in/src-d/go-git.v4/plumbing/transport/ssh
/home/ckamphaus/go/src/gopkg.in/src-d/go-git.v4/plumbing/transport/ssh/common.go:147:15: undefined: proxy.Dial

I'm using
go version go1.13.6 linux/amd64
GOPATH="/home/ckamphaus/go"
OS is Linux Mint 19.3
Current latest commit on master is 3918253.

Go get error "not enough arguments in call to d.prompt.Run"

I have no experience with go get and I can't find any similar solution on the web so please excuse my ignorance. Here's the error output:

~ 🞂🞂 go get github.com/isacikgoz/tldr/cmd/tldr

# github.com/isacikgoz/tldr/cli
go/src/github.com/isacikgoz/tldr/cli/default.go:59:21: not enough arguments in call to d.prompt.Run
        have ()
        want (context.Context)

Some issues in v1.0.0-alpha

I've been using tldr++ version 0.6.1 for some time and it has been a great experience. Thank you very much for developing this!
There are a couple of issues in your latest release (tested on Xubuntu 18.04 in i3wm session) :
1- There is a considerable keyboard input latency (lag) when tldr is invoked (~ 1-2 seconds for each key press). For version 0.6.1 it was maybe ~500 ms.
2- For searching a command, you have to first use "/" which I find redundant. Since the user invokes tldr for searching a command, why make it harder by first pressing another key.
3- The number of default suggestions has been lowered to a couple of lines (personally I preferred the former 6 lines of suggestions).

A couple of feature requests 😉:
4- It would have been nice to be able to exit tldr with Esc key (currently only CTRL+C is possible).
5- When a command is completed in tldr, the command wouldn't get saved to bash history. I think this happens because you directly invoke the command in Go. Maybe you could instead exec the command directly on bash so it would be saved to history (or at least provide the option for doing so).

BTW, I think you should popularize your project more (over hackernews, reddit, etc). I think currently it is the only tldr client with fuzzy search + interactive completion of CLI tools switches.
Cheers 💯

Operating system not recognized

Tool doesn't work in termux, says operating system not recognized. I don't see any reasons why it shouldn't work and unfortunately there's no flag to disable this check.

[Request] Make the local settings dir(s) configurable?

Hey, great work on this version of a tldr client 👍

I've recently started using tldr quite a lot, but I also have my own collection of markdown snippets which I've typically accessed via. vim in the past. It would be really be nice if I could consolidate them into tldr.

Is there any possibility of either a way to override the config directory and/or add another directory to index, so tldr could scan both the canonical resource and my own folder(s)? That way I could use my own snippets - some of which can't be contributed upstream to tldr - using the same tool.

For example, functionality like the following to override and use only my own resources, would be awesome.

# Override the man dir and only use my custom snippets
tldr --man-dir ~/.tldr git
# or add my own snippets on top of the normal tldr snippets
tldr --additional-dir ~/.tldr git

Cheers,
James.

Go 1.18 debug/buildinfo feature

See: https://shibumi.dev/posts/go-18-feature/

Don't suggest to update with -u if already using -u

❯ tldr -u
TLDR repository is older than 2 weeks, consider updating it with -u option.
[...]

Data race in package prompt

When building with -race (cd cmd/tldr; go build -race; ./tldr ps) I can easily get a data race report.

==================
WARNING: DATA RACE
Read at 0x00c0001280b0 by goroutine 8:
  github.com/isacikgoz/gitin/prompt.(*Prompt).spawnEvents()
      $GOPATH/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:180 +0xef

Previous write at 0x00c0001280b0 by main goroutine:
  github.com/isacikgoz/gitin/prompt.(*Prompt).mainloop()
      $GOPATH/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:227 +0x364
  github.com/isacikgoz/gitin/prompt.(*Prompt).Run()
      $GOPATH/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:145 +0x1cc
  main.run()

I don't know if this is related to #23, but at least this happens in the same package.

go version

go version go1.13.6 darwin/amd64

Commit: 3918253

Ability to append user-defined examples

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

The tool is really helpful when it comes to search predefined / crowd-sourced repository-derived examples, but falls short when the end user wants to append its own one-liners.

Expected Behavior

The ability to append, edit, mix and match preexisting / new examples / one-liners, on the fly or statically.

Steps To Reproduce

No response

Environment

- OS: elementary OS 6.1 Jólnir x86_64
- Terminal emulator: Alacritty
- Go version: go version go1.13.8 linux/amd64k

Anything else?

Another tldr client already implements a similar feature, but more of a static approach i.e. a patch file has to be edited beforehand, rather than dynamically search, edit and add.

Use XDG_STATE_HOME

To store the tldr pages, as this is not actual application data and thus does not belong into DATA ("share") anymore: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Usability issues

Hi fellow tldr implementer! I wanted to try your client, so I installed 0.6.1 on Arch via AUR.

When I run it the first time, it looks like this:

(Note: This must have something to do with some control characters, since when I make the window small and large again, there is a proper line break. I'm using alacritty as a terminal emulator, in case that's relevant.)

So since the command asked me to re-run it with -u, I did so. However, this results in the same warning being printed again.

So I thought, maybe I need to combine -u with a page name. But that doesn't seem to do anything either...

Another theory was that it's broken in the interactive mode, but works in static mode. But with tldr -s -u, the cache isn't pulled either.

TL;DR: I don't know how to use your tool 😄 It could well be that I'm too stupid to use it properly, but my experience may be useful to improve the API!

Output reprints every action

Expected Behavior (from README):

Actual Behavior:

The output gets reprinted in full every time an action is made. In the README it does not appear to work this way but if I am mistaken please close this issue. Thanks!

Language setting

How to set the language used? According to locale environment variable or a config file?

Go get fails with "no Go files in ..."

Not sure if I'm missing something, but I'm getting the following output when I try to install with go get:

$ go get -u github.com/isacikgoz/tldr
package github.com/isacikgoz/tldr: no Go files in /home/user/go/src/github.com/isacikgoz/tldr

I'm not familiar with how go packages are formatted, but it looks like it cloned the repo properly to /home/user/go/src/github.com/isacikgoz/tldr.

go get fails

Install fails:
$ go get -u github.com/isacikgoz/tldr

cd /home//prj/go/src/gopkg.in/src-d/go-git.v4; git pull --ff-only

Your configuration specifies to merge with the ref 'refs/heads/v4'
from the remote, but no such ref was fetched.
package gopkg.in/src-d/go-git.v4: exit status 1

Go version: go version go1.10.4 linux/amd64
OS: Pop_OS 19.04 (basically Ubuntu 19.04)
GOPATH: /home//prj/go

Release can't work

Hello,

I downloaded tldr_0.5.0_linux_arm64.tar.gz, and found it can not work :

➜  ~ ./tldr --help
usage: tldr [<flags>] [<command>...]

Flags:
      --help         Show context-sensitive help (also try --help-long and --help-man).
  -c, --clear-cache  Clear local repository then clone github.com/tldr-pages/tldr
  -u, --update       Pulls the latest commits from github.com/tldr-pages/tldr
  -s, --static       Static mode, application behaves like a conventional tldr client.
  -r, --random       Random page for testing purposes.
      --version      Show application version.

Args:
  [<command>]  Name of the command. (e.g. tldr grep)

➜  ~ ./tldr -u
➜  ~ ./tldr tar
This page (tar) doesn't exist yet!
Submit new pages here: https://github.com/tldr-pages/tldr#                                                              
➜  ~ ./tldr zip
This page (zip) doesn't exist yet!
Submit new pages here: https://github.com/tldr-pages/tldr#                                                              
➜  ~ ./tldr -r
panic: invalid argument to Intn

goroutine 1 [running]:
math/rand.(*Rand).Intn(0xc4200821b0, 0x0, 0x157c599f75927412)
        /usr/lib/go-1.10/src/math/rand/rand.go:166 +0x9c
math/rand.Intn(0x0, 0x74fc9f)
        /usr/lib/go-1.10/src/math/rand/rand.go:326 +0x37
github.com/isacikgoz/tldr/pkg/pages.QueryRandom(0x0, 0x0, 0x0)
        /home/isacikgoz/.local/share/go/src/github.com/isacikgoz/tldr/pkg/pages/pages.go:90 +0x60e
main.main()
        /home/isacikgoz/git/tldr/main.go:31 +0x567

Error: exec: executable file not found in %PATH%

On windows, tldr is unable to execute the commands once selected:

>tldr winget

winget

Windows Package Manager CLI.
More information: <https://docs.microsoft.com/windows/package-manager/winget>.

  Search for a package
   winget search package

$ package -> terminal
? winget search terminal Yes
exec: "winget": executable file not found in %PATH%

The error message is incorrect since winget is, indeed, in my PATH

Use shell autocompletion for filling in placeholders

Idk how feasible this is, but interactively typing paths & co is tedious, maybe shell tab-completion can be leveraged somehow...

compile error

i tried to get tldr today and it resulted in this error:

# github.com/isacikgoz/tldr/cli
../../../go/src/github.com/isacikgoz/tldr/cli/default.go:44:33: cannot use list (type *"github.com/isacikgoz/gitin/prompt".SyncList) as type *"github.com/isacikgoz/gitin/prompt".List in argument to defaultExitMessage:
	*"github.com/isacikgoz/gitin/prompt".List is pointer to interface, not interface
../../../go/src/github.com/isacikgoz/tldr/cli/default.go:82:15: l.Items undefined (type *"github.com/isacikgoz/gitin/prompt".List is pointer to interface, not interface)

i ran go get github.com/isacikgoz/tldr/cmd/tldr

Overzealous virus detector will false-positive.

I'm using Acronis trueimage (Though it apparently also happens with BitDefender) and after installing with chocolatey it thinks tldr++ has "gen:variant.ser.ursu.3230".

According to internet research this can be adjusted by giving the executable an icon

https://stackoverflow.com/questions/58010466/bitdefender-detects-my-console-application-as-genvariant-ursu-56053

console stdin breaks after <Ctrl+ C> during suggestion completion

Installation information

I've built tldr++ from source using:

git clone https://github.com/isacikgoz/tldr/
cd cmd/tldr
go install

I'm using go version go1.15.3 linux/amd64 on ubuntu 20.04

Steps to reproduce

1. tldr tar, for example
2. Select any suggestion/option (press Enter)
3. Press Ctrl + C

Expected behaviour

Now able to use bash/shell normally

Actual behaviour

Subsequent stdin and newlines after commands are not shown in console.

Above is bug in action. I've typed Enter some times and echo hi.

PS. I've come into contact with this bug in the past when programming in Go when handling os.Stdout and os.Stdin.

Wrong Condition and append in `ConfirmCommand` function

In cli/confirm.go file from line 24:27 doesn't make sense!

if s.Text() == "Y!" || s.Text() == "y!" {
	args = []string{"sudo"}
	args = append(strings.Fields(command))
}

Reason is, this block of code will never be executed. As s.Text() is either [Y, y, ``], according to previous condition.

Second is here args = []string{"sudo"}, sudo is never really prepended in args list as you are overriding args in next line!

A quick fix could be following:

if s.Text() == "Y" || s.Text() == "y" || s.Text() == "" ||
	s.Text() == "Y!" || s.Text() == "y!" { // add those condition to previous one
	args := strings.Fields(command)
	if s.Text() == "Y!" || s.Text() == "y!" {
		args = append([]string{"sudo"}, args...) // add sudo as first arg
	}
...
}

Now when I tried above fix I am getting another issue:

? ls -a (Y/n) y!
args:  [sudo ls -a] # added print for log purpose
Password:panic: send on closed channel

goroutine 5 [running]:
github.com/isacikgoz/gitin/prompt.(*Prompt).spawnEvents(0xc0001440c0)
        /Users/lenin/go/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:186 +0x119
created by github.com/isacikgoz/gitin/prompt.(*Prompt).Run
        /Users/lenin/go/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:141 +0xd2

Is this a known issue to you?

Make tldr-pages repo configurable

Hello.
First of all, really great looking client. I might start using it as my tldr client, but for that I need to be able to point the tool to my own fork of tldr-pages repository instead of "github.com/tldr-pages/tldr".

What do you think?

No output for failed commands

> tldr curl
Transfers data from or to a server.
Supports most protocols, including HTTP, FTP, and POP3.
More information: <https://curl.se>.

  Download the contents of an URL to a file
  curl http://example.com -o filename

$ http://example.com -> 
$ filename -> 
? curl  -o  [Y/n] y
exit status 2

> curl -o                                 
curl: option -o: requires parameter
curl: try 'curl --help' for more information

If command failed - I can only know the exit code, sometimes it's very hard to understand what's wrong because of that.

[non-issue] hosting images

Doesn't work with yay

I tried using tldr with yay, just to test it out, and got the following output:

 ~ $ tldr yay

yay

Yet Another Yogurt: A utility for Arch Linux to build and install packages from the Arch User Repository.
Also see `pacman`.

  Synchronize and update only AUR packages
   yay -Sua

? yay -Sua Yes
:: Searching AUR for updates...
 -> hsakmt-roct: local (1.8.3.r0.e3dd067-1) is newer than AUR (1.8.0.r0.e3dd067-2)
 -> Missing AUR Packages:  firefox-extension-shumway  gegl02  pcmciautils
 -> Out Of Date AUR Packages:   hsa-rocr  hsakmt-roct  mailpile
:: 2 Packages to upgrade.
2  aur/google-chrome  71.0.3578.98-1 -> 72.0.3626.81-1
1  aur/xnviewmp       0.92-1         -> 0.93-1
==> Packages to not upgrade: (eg: 1 2 3, 1-3, ^4 or repo name)
==> ^M^M 

In summary, my enter key was being eaten and converted to ^M rather than being registered by yay directly. Is this an issue with tldr++ or should I take it up with whoever maintains yay?

Compilation error

Hi! This project seems to present an interesting usability approach to tldr clients. Congrats!

Unfortunately, I didn't have the opportunity to test it, since I couldn't manage to compile it. It seems to be an error on one of your dependencies. The output of go get github.com/isacikgoz/tldr/cmd/tldr:

# github.com/c-bata/go-prompt/internal/term
go/src/github.com/c-bata/go-prompt/internal/term/raw.go:27:75: cannot use (*syscall.Termios)(&n) (type *syscall.Termios) as type *unix.Termios in argument to termios.Tcsetattr
go/src/github.com/c-bata/go-prompt/internal/term/term.go:22:40: cannot use &saveTermios (type *syscall.Termios) as type *unix.Termios in argument to termios.Tcgetattr
go/src/github.com/c-bata/go-prompt/internal/term/term.go:33:68: cannot use &o (type *syscall.Termios) as type *unix.Termios in argument to termios.Tcsetattr

[BUG] Highlighting off when term is repeated

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

It functionally works correctly, but in the preview the first occurence of the word rather than the actually substituted one is highlighted.

Expected Behavior

the actual parameter is highlighted

Steps To Reproduce

tldr emacsclient

Environment

- OS: Arch
- Terminal emulator: Kitty

Anything else?

No response

Unexpected Escape Sequence: ['\x1b' 'O'] on tmux.

Hi!

When use like
tldr tar
and try to move down or up it gives me that error

Unexpected Escape Sequence: ['\x1b' 'O']
Is there any way to fix this or is this not tmux friendly?

Bug: Panic on any prompt input

When inputting anything on any prompt shown in response to selecting a command pattern, tldr crashes. The panic happens in package gitin due to a send on a closed channel, but this needn't mean it isn't caused by the application.

> tldr tar
Archiving utility.
Often combined with a compression method, such as gzip or bzip.
More information: <https://www.gnu.org/software/tar>.

  Extract an archive into a target directory
  tar xf source.tar -C directory

$ source.tar -> panic: send on closed channel

goroutine 7 [running]:
github.com/isacikgoz/gitin/prompt.(*Prompt).spawnEvents(0xc00014c000)
        /home/curio77/.go/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:185 +0xf2
created by github.com/isacikgoz/gitin/prompt.(*Prompt).Run
        /home/curio77/.go/pkg/mod/github.com/isacikgoz/[email protected]/prompt/prompt.go:141 +0xf0

Not work command when input parameter

My English is not good, so use bash content to explain my problem

Not work

caesar@caesar-VirtualBox:~/go/bin 
$ ./tldr ps

ps

Information about running processes.

  Search for a process that matches a string
   ps aux | grep string

$ string -> go
? ps aux | grep go Yes
error: garbage option

Usage:
 ps [options]

 Try 'ps --help <simple|list|output|threads|misc|all>'
  or 'ps --help <s|l|o|t|m|a>'
 for additional help text.

For more details see ps(1).
exit status 1

---

OK work

caesar@caesar-VirtualBox:~/go/bin 
$ ps aux | grep go
caesar    1055  0.0  0.0  21540  1060 pts/5    S+   16:43   0:00 grep --color=auto go
caesar   31092  0.0  0.4 782004 32732 ?        Sl   16:36   0:00 /usr/lib/gnome-online-accounts/goa-daemon
caesar   31102  0.0  0.1 319876 10168 ?        Sl   16:36   0:00 /usr/lib/gnome-online-accounts/goa-identity-service
caesar   31146  0.0  0.0 274220  6124 ?        Ssl  16:36   0:00 /usr/lib/gvfs/gvfs-goa-volume-monitor

Zsh autocompletion

Add simple zsh-completion

Use default value when none is privded

Rather than an empty one, which rarely works well. The placeholders sometimes contain actual useful values.

Panic when running `tldr -r`

After a fresh install of tldr++ 0.6.1 on Arch (via AUR), when I simply run tldr -r (without updating the cache first), I get a panic.

danilo@x2000:~$ tldr -r
TLDR repository is older than 2 weeks, consider updating it with -u option.
panic: invalid argument to Intn

goroutine 1 [running]:
math/rand.(*Rand).Intn(0xc00007c420, 0x0, 0x557e01f9c1c0)
	math/rand/rand.go:169 +0x9e
math/rand.Intn(...)
	math/rand/rand.go:337
github.com/isacikgoz/tldr/pkg/pages.QueryRandom(0x0, 0x0, 0x0)
	github.com/isacikgoz/tldr/pkg/pages/pages.go:90 +0x42f
main.main()
	github.com/isacikgoz/tldr/main.go:31 +0x5b5

[BUG] go install instructions don't work

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

$ go install github.com/isacikgoz/tldr/cmd/tldr@latest
go: github.com/isacikgoz/tldr/cmd/tldr@latest: module github.com/isacikgoz/tldr@latest found (v0.6.1), but does not contain package github.com/isacikgoz/tldr/cmd/tldr
$ go version
go version go1.21.0 darwin/arm64

Expected Behavior

Install should proceed

Steps To Reproduce

Run the install instructions from the readme

Environment

- OS: macOS 13.5 (22G74)
- Terminal emulator: irrelevant
- Go version: go1.21.0

Anything else?