[ANNOUNCE] tig - text-mode interface for git

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello,

I am pleased to announce tig, a simple git repository browser written
using ncurses. Basically, it just acts as a front-end for git-log and
git-show/git-diff. Additionally, you can also use it as a pager for git
commands.

Currently, it just provides a minimum support for looking through
changes. I hope to slowly extend it to also be usable as a front-end for
git-blame and for tree browsing. Also, it doesn't do any fancy revision
graph rendering, but I want to at least give it a shot at some point. :)

Following is the man page. I've attached the tig.c file if you want to
try it out. Compile it with:

	$ cc -o tig tig.c -lncurses

More project files (including a Makefile) can be found at:

	http://jonas.nitro.dk/tig/

Obligatory screenshots at:

	http://jonas.nitro.dk/tig/screenshots/

---

NAME

   tig - text-mode interface for git

SYNOPSIS

   tig [options]
   tig [options] [--] [git log options]
   tig [options] log  [git log options]
   tig [options] diff [git diff options]
   tig [options] show [git show options]
   tig [options] <    [git command output]

DESCRIPTION

   Browse changes in a git repository. Additionally, tig(1) can also act
   as a pager for output of various git commands.

   When browsing repositories, tig(1) uses the underlying git commands
   to present the user with various views, such as summarized commit log
   and showing the commit with the log message, diffstat, and the diff.

   Using tig(1) as a pager, it will display input from stdin and try to
   colorize it.

OPTIONS

   -l
           Start up in log view using the internal log command.

   -d
           Start up in diff view using the internal diff command.

   -n[INTERVAL], --line-number[=INTERVAL]
           Prefix line numbers in log and diff view. Optionally, with
           interval different than each line.

   -t[NSPACES], --tab-size[=NSPACES]
           Set the number of spaces tabs should be expanded to.

   -v, --version
           Show version and exit.

   --
           End of tig(1) options. Useful when specifying command options
           for the main view. Example:

		$ tig -- --since=1.month

   log [git log options]
           Open log view using the given git log options.

   diff [git diff options]
           Open diff view using the given git diff options.

   show [git show options]
           Open diff view using the given git show options.

   [git log options]
           tig(1) will stop the option parsing when the first command
           line parameter not starting with "-" is encountered. All
           options including this one will be passed to git log when
           loading the main view. This makes it possible to say:

		$ tig tag-1.0..HEAD

  Pager mode

   If stdin is a pipe, any log or diff options will be ignored and the
   pager view will be opened loading data from stdin. The pager mode can
   be used for colorizing output from various git commands.

   Example on how to colorize the output of git-show(1):

	$ git show | tig

  Git command options

   All git command options specified on the command line will be passed
   to the given command and all will be shell quoted before they are
   passed to the shell.

        If you specify options for the main view, you should not use the
   Note --pretty option as this option will be set automatically to the
        format expected by the main view.

   Example on how to open the log view and show both author and
   committer information:

	$ tig log --pretty=fuller

   See the "Specifying revisions" section below for an introduction to
   revision options supported by the git commands. For details on
   specific git command options, refer to the man page of the command in
   question.

ENVIRONMENT VARIABLES

   Several options related to the interface with git can be configured
   via environment options.

  Repository references

   Commits that are referenced by tags and branch heads will be marked
   by the reference name surrounded by [ and ]:

	2006-03-26 19:42 Petr Baudis       | [cogito-0.17.1] Cogito 0.17.1

   If you want to filter out certain directories under .git/refs/, say
   tmp you can do it by setting the following variable:

	$ TIG_LS_REMOTE="git ls-remote . | sed /\/tmp\//d" tig

   Or set the variable permanently in your environment.

   TIG_LS_REMOTE

           Set command for retrieving all repository references. The
           command should output data in the same format as
           git-ls-remote(1).

  View commands

   It is possible to alter which commands are used for the different
   views. If for example you prefer commits in the main view to be
   sorted by date and only show 500 commits, use:

	$ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %s" tig

   Or set the variable permanently in your environment.

   Notice, how %s is used to specify the commit reference. There can be
   a maximum of 5 %s ref specifications.

   TIG_DIFF_CMD

           The command used for the diff view. By default, git show is
           used as a backend.

   TIG_LOG_CMD

           The command used for the log view. If you prefer to have both
           author and committer shown in the log view be sure to pass
           --pretty=fuller to git log.

   TIG_MAIN_CMD

           The command used for the main view. Note, you must always
           specify the option: --pretty=raw since the main view parser
           expects to read that format.

The viewer

   tig(1) presents various views of a repository. Each view is based on
   output from an external command, most often git log, git diff, or git
   show.

   The main view
           Is the default view, and it shows a one line summary of each
           commit in the chosen list of revisions. The summary includes
           commit date, author, and the first line of the log message.
           Additionally, any repository references, such as tags, will
           be shown.

   The log view
           Presents a more rich view of the revision log showing the
           whole log message and the diffstat.

   The diff view
           Shows either the diff of the current working tree, that is,
           what has changed since the last commit, or the commit diff
           complete with log message, diffstat and diff.

   The pager view
           Is used for displaying both input from stdin and output from
           git commands entered in the internal prompt.

   The help view
           Displays the information from the tig(1) man page. For the
           help view to work you need to have the tig(1) man page
           installed.

KEYS

   Below the default key bindings are shown.

  View switching

   m       Switch to main view.
   d       Switch to diff view.
   l       Switch to log view.
   p       Switch to pager view.
   h       Show man page.
   Return  If on a commit line show the commit diff. Additionally, if in
           main or log view this will split the view. To open the commit
           diff in full size view either use d or press Return twice.
   Tab     Switch to next view.

  Cursor navigation

   Up      Move cursor one line up.
   Down    Move cursor one line down.
   k       Move cursor one line up and enter. When used in the main view
           this will always show the diff of the current commit in the
           split diff view.
   j       Move cursor one line down and enter.
   PgUp    Move cursor one page up.
   PgDown  Move cursor one page down.
   Home    Jump to first line.
   End     Jump to last line.

  Scrolling

   Insert  Scroll view one line up.
   Delete  Scroll view one line down.
   w       Scroll view one page up.
   s       Scroll view one page down.

  Misc

   q       Quit
   r       Redraw screen.
   z       Stop all background loading. This can be useful if you use
           tig(1) in a repository with a long history without limiting
           the revision log.
   v       Show version.
   n       Toggle line numbers on/off.
   :       Open prompt. This allows you to specify what git command to
           run. Example:

		:log -p

Revision specification

   This section describes various ways to specify what revisions to
   display or otherwise limit the view to. tig(1) does not itself parse
   the described revision options so refer to the relevant git man pages
   for futher information. Relevant man pages besides git-log(1) are
   git-diff(1) and git-rev-list(1).

   You can tune the interaction with git by making use of the options
   explained in this section. For example, by configuring the
   environment variables described in the "View commands" section.

  Limit by path name

   If you are interested only in those revisions that made changes to a
   specific file (or even several files) list the files like this:

	$ tig log Makefile

   To avoid ambiguity with repository references such as tag name, be
   sure to separate file names from other git options using "--". So if
   you have a file named master it will clash with the reference named
   master, and thus you will have to use:

	$ tig log -- master

        For the main view, avoiding ambiguity will in some cases require
   Note you to specify two "--" options. The first will make tig(1) stop
        option processing and the latter will be passed to git log.

  Limit by date or number

   To speed up interaction with git, you can limit the amount of commits
   to show both for the log and main view. Either limit by date using
   e.g. --since=1.month or limit by the number of commits using -n400.

   If you are only interested in changed that happened between two dates
   you can use:

	$ tig -- --after=May.5th --before=2006-05-16.15:44

        The dot (".") is used as a separator instead of a space to avoid
   Note having to quote the option value. If you prefer use --after="May
        5th" instead of --after="May 5th".

  Limiting by commit ranges

   Alternatively, commits can be limited to a specific range, such as
   "all commits between tag-1.0 and tag-2.0". For example:

	$ tig log tag-1.0..tag-2.0

   This way of commit limiting makes it trivial to only browse the
   commits which haven't been pushed to a remote branch. Assuming origin
   is your upstream remote branch, using:

	$ tig log origin..HEAD

   will list what will be pushed to the remote branch. Optionally, the
   ending HEAD can be left out since it is implied.

  Limiting by reachability

   Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
   reachable from tag-2.0 but not from tag-1.0". Where reachability
   refers to what commits are ancestors (or part of the history) of the
   branch or tagged revision in question.

   If you prefer to specify which commit to preview in this way use the
   following:

	$ tig log tag-2.0 ^tag-1.0

   You can think of ^ as a negation operator. Using this alternate
   syntax, it is possible to further prune commits by specifying
   multiple branch cut offs.

  Combining revisions specification

   Revisions options can to some degree be combined, which makes it
   possible to say "show at most 20 commits from within the last month
   that changed files under the Documentation/ directory."

	$ tig -- --since=1.month -n20 -- Documentation/

  Examining all repository references

   In some cases, it can be useful to query changes across all
   references in a repository. An example is to ask "did any line of
   development in this repository change a particular file within the
   last week". This can be accomplished using:

	$ tig -- --all --since=1.week -- Makefile

BUGS

   Known bugs and problems:

     * If the screen width is very small the main view can draw outside
       the current view causing bad wrapping. Same goes for title and
       status windows.

TODO

   Features that should be explored.

     * Searching.

     * Locale support.

COPYRIGHT

   Copyright (c) Jonas Fonseca <fonseca@xxxxxxx>, 2006

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or (at
   your option) any later version.

SEE ALSO

   git(7),
   cogito(7)
   gitk(1): git repository browser written using tcl/tk,
   gitview(1): git repository browser written using python/gtk.

-- 
Jonas Fonseca
-
: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]