From 5a4f89414cbc31c8c8417f2bc91077a719ae3203 Mon Sep 17 00:00:00 2001 From: Thomas Koutcher Date: Sat, 25 Jan 2020 19:48:54 +0100 Subject: [PATCH] Add troubleshooting information --- Makefile | 7 +++- README.adoc | 3 ++ TROUBLESHOOTING.adoc | 97 ++++++++++++++++++++++++++++++++++++++++++++ book.md | 1 + contrib/tig.spec.in | 2 +- 5 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 TROUBLESHOOTING.adoc diff --git a/Makefile b/Makefile index c5dae2741..6fbb0b084 100644 --- a/Makefile +++ b/Makefile @@ -48,9 +48,9 @@ RPM_RELEASE = $(word 2,$(RPM_VERLIST))$(if $(WTDIRTY),.dirty) DFLAGS = -g -DDEBUG -Werror -O0 EXE = src/tig TOOLS = test/tools/test-graph tools/doc-gen -TXTDOC = doc/tig.1.adoc doc/tigrc.5.adoc doc/manual.adoc NEWS.adoc README.adoc INSTALL.adoc test/API.adoc +TXTDOC = doc/tig.1.adoc doc/tigrc.5.adoc doc/manual.adoc NEWS.adoc README.adoc TROUBLESHOOTING.adoc INSTALL.adoc test/API.adoc MANDOC = doc/tig.1 doc/tigrc.5 doc/tigmanual.7 -HTMLDOC = doc/tig.1.html doc/tigrc.5.html doc/manual.html README.html INSTALL.html NEWS.html +HTMLDOC = doc/tig.1.html doc/tigrc.5.html doc/manual.html README.html TROUBLESHOOTING.html INSTALL.html NEWS.html ALLDOC = $(MANDOC) $(HTMLDOC) doc/manual.html-chunked doc/manual.pdf # Never include the release number in the tarname for tagged @@ -403,6 +403,9 @@ doc/manual.html: ASCIIDOC_FLAGS += -ainclude-manual-toc README.html: README.adoc doc/asciidoc.conf $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article -a readme $< +TROUBLESHOOTING.html: TROUBLESHOOTING.adoc doc/asciidoc.conf + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article $< + INSTALL.html: INSTALL.adoc doc/asciidoc.conf $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article $< diff --git a/README.adoc b/README.adoc index c4b515ec8..6e104c90b 100644 --- a/README.adoc +++ b/README.adoc @@ -26,6 +26,9 @@ Resources Bugs and Feature Requests ------------------------- +Please check out link:TROUBLESHOOTING.{docext}[the troubleshooting guide] +if you are experiencing issues with Tig. + Bugs and feature requests can be reported using the https://github.com/jonas/tig/issues[issue tracker] or by mail to either the Git mailing list or directly to the maintainer. Ensure that the word diff --git a/TROUBLESHOOTING.adoc b/TROUBLESHOOTING.adoc new file mode 100644 index 000000000..e02f26a0e --- /dev/null +++ b/TROUBLESHOOTING.adoc @@ -0,0 +1,97 @@ +Troubleshooting +=============== +:docext: adoc + +Display +------- + +Tig is based on ncurses and relies on the terminal characteristics +stored in the terminfo database. If you are lying about the capabilities +of your terminal, you cannot expect Tig to work properly. + +ncursesw +~~~~~~~~ + +If you did not compile Tig with `ncursesw` (or default `ncurses` on +macOS) then Unicode characters cannot be displayed. + +To make sure which ncurses version you are using, first confirm +which `tig` executable you are running and then use `ldd -r` (Linux) or +`otool -L` (macOS). + +If mouse scroll down does not work, check that ncurses was compiled +with `--enable-ext-mouse`. See https://bugs.debian.org/838376 for +more details. + +TERM +~~~~ + +The `TERM` variable must be set in accordance with your terminal type. + +If you are using a terminal multiplexer like GNU screen or tmux (but not +dtach), then the `TERM` variable *before* starting the terminal multiplexer +must be set in accordance with your terminal type and the `TERM` variable +*inside* the terminal multiplexer must be set to `screen` or any +compatible variant. + +You can check with `infocmp` that you have the proper entry for your +terminal type in your terminfo database. +If you want to use an alternate terminfo database, you can use +`export TERMINFO=/path/to/terminfo`. + +Some OS (e.g. OS X 10.11) are shipping with an incomplete terminfo +description for screen resulting, for example, in the diff-highlight +option not working when running Tig inside screen/tmux. It can be +fixed locally (for the current user) with: +``` +curl -O https://invisible-island.net/datafiles/current/terminfo.src.gz +gunzip terminfo.src +tic -x -o "$HOME/.terminfo" -e screen terminfo.src +``` + +Note that macOS still comes with and old version of ncurses (5.7) which +may not work well with newer 256-color terminfo entries. + +Note that while PuTTY identifies itself by default as `xterm`, it is +not fully compatible with it. If you have problems with the keyboard +mapping (e.g. Home/End), try to use `putty` instead. Check out +https://invisible-island.net/xterm/xterm.faq.html#known_bugs[XTerm FAQ] +for more details and information on other terminal emulators. + +LANG +~~~~ + +The `LANG` variable must be set in accordance with your terminal +encoding settings. If the `LANG` variable is not properly set, +accented characters will be distorted. + +Use `locale -a` to check if your `LANG` variable is present in the +list of available locales (on Linux, you may find that `UTF-8` has +been substituted for `utf8` but they are equivalent). + +Note that the ability to set the `LANG` variable to values such as +`en_DE` with KDE does not imply their validity. + +Also check the `LC_ALL` variable as it has precedence over `LANG`. + +ESCDELAY +~~~~~~~~ + +See ESCDELAY environment variable in ncurses(3x) to reduce the one +second delay after pressing the escape key. Nowadays, +`export ESCDELAY=100` should be more than enough. + +Git +--- + +Tig relies entirely on Git to access your repository data. If Tig fails +to show any commit, first check the corresponding `git log` command. To +find out which options Tig is using, try `TIG_TRACE=/tmp/tig.log tig`. + +Note that Tig's command line parser is not as permissive as that of Git. +For example, arguments such as -S/-G or --grep must be passed without +space: +``` +tig -G"" +tig --grep="" +``` diff --git a/book.md b/book.md index fd2b3bbaf..aa7866b7c 100644 --- a/book.md +++ b/book.md @@ -2,6 +2,7 @@ - [Installation](INSTALL.adoc) - [Release notes](NEWS.adoc) + - [Troubleshooting](TROUBLESHOOTING.adoc) - [tig(1)](doc/tig.1.adoc) - [tigrc(5)](doc/tigrc.5.adoc) - [Manual](doc/manual.adoc) diff --git a/contrib/tig.spec.in b/contrib/tig.spec.in index ee24afbe6..a821b9c9e 100644 --- a/contrib/tig.spec.in +++ b/contrib/tig.spec.in @@ -48,7 +48,7 @@ CFLAGS="$RPM_OPT_FLAGS -DVERSION=tig-%{version}-%{release}" %defattr(-,root,root) %{_bindir}/* %{_sysconfdir}/* -%doc README.adoc COPYING INSTALL.adoc NEWS.adoc contrib/tig-completion.bash contrib/tig-completion.zsh +%doc README.adoc COPYING TROUBLESHOOTING.adoc INSTALL.adoc NEWS.adoc contrib/tig-completion.bash contrib/tig-completion.zsh %{!?_without_docs: %{_mandir}/man1/*.1*} %{!?_without_docs: %{_mandir}/man5/*.5*} %{!?_without_docs: %{_mandir}/man7/*.7*}