Split out manual material to separate file

diff --git a/Makefile b/Makefile
index 1a3dc15ca4e5341ef20c05ebcf1b93c57461c0c2..ac545e6a3d2ab1c6081c8a2dc9eb4f725ecea9f7 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,8 @@ LDLIBS  = -lcurses
 CFLAGS = -Wall -O2
 DFLAGS = -g -DDEBUG -Werror
 PROGS  = tig
-DOCS   = tig.1.txt tig.1.html tig.1 tigrc.5.html tigrc.5 README.html
+DOCS   = tig.1.txt tig.1.html tig.1 tigrc.5.html tigrc.5 \
+         manual.html manual.html-chunked README.html
 
 ifneq (,$(wildcard .git))
 VERSION = $(shell git-describe)
@@ -30,6 +31,7 @@ install-docs: docs
        done
 
 clean:
+       rm -rf manual.html-chunked
        rm -f $(PROGS) $(DOCS) core
 
 spell-check:
@@ -65,3 +67,12 @@ README.html: README
 
 %.5 : %.5.xml
        xmlto man $<
+
+%.html : %.txt
+       asciidoc -b xhtml11 -d article $<
+
+%.xml : %.txt
+       asciidoc -b docbook -d article $<
+
+%.html-chunked : %.xml
+       xmlto html -o $@ $<

diff --git a/manual.txt b/manual.txt
new file mode 100644 (file)
index 0000000..775c8c5
--- /dev/null
+++ b/manual.txt
@@ -0,0 +1,386 @@
+The tig Manual
+==============
+Jonas Fonseca <fonseca@diku.dk>
+
+This is the manual for tig, the ncurses-based text-mode interface for git.
+Tig allows you to browse changes in a git repository and can additionally act
+as a pager for output of various git commands. When used as a pager, it will
+display input from stdin and colorize it.
+
+When browsing repositories, tig 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.
+
+Calling Conventions
+-------------------
+
+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.
+
+NOTE: If you specify options for the main view, you should not use the
+`--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 <<refspec, "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).
+
+[[history-commands]]
+History 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
+----------
+
+The display consists of a status window on the last line of the screen and one
+or more views. The default is to only show one view at the time but it is
+possible to split both the main and log view to also show the commit diff.
+
+If you are in the log view and press 'Enter' when the current line is a commit
+line, such as:
+
+       commit 4d55caff4cc89335192f3e566004b4ceef572521
+
+You will split the view so that the log view is displayed in the top window
+and the diff view in the bottom window. You can switch between the two views
+by pressing 'Tab'. To maximize the log view again, simply press 'l'.
+
+Current Head and Commit ID
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The viewer keeps track of both what head and commit ID you are currently
+viewing. The commit ID will follow the cursor line and change everytime time
+you highlight a different commit. Whenever you reopen the diff view it will be
+reloaded, if the commit ID changed.
+
+The head ID is used when opening the main and log view to indicate from what
+revision to show history.
+
+Views
+~~~~~
+
+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.
+
+Title Windows
+~~~~~~~~~~~~~
+
+Each view has a title window which shows the name of the view, current commit
+ID if available, and where the view is positioned:
+
+       [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
+
+By default, the title of the current view is highlighted using bold font.  For
+long loading views (taking over 3 seconds) the time since loading started will
+be appended:
+
+       [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
+
+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.
+
+View Manipulation
+~~~~~~~~~~~~~~~~~
+q::
+       Close view, if multiple views are open it will jump back to the
+       previous view in the view stack. If it is the last open view it
+       will quit. Use 'Q' to quit all views at once.
+Enter::
+       This key is "context sensitive" depending on what view you are
+       currently in. When in log view on a commit line or in the main
+       view, split the view and show the commit diff. In the diff view
+       pressing Enter will simply scroll the view one line down.
+Tab::
+       Switch to next view.
+Up::
+       This key is "context sensitive" and will move the cursor one
+       line up. However, uf you opened a diff view from the main view
+       (split- or full-screen) it will change the cursor to point to
+       the previous commit in the main view and update the diff view
+       to display it.
+Down::
+       Similar to 'Up' but will move down.
+
+Cursor Navigation
+~~~~~~~~~~~~~~~~~
+j::
+       Move cursor one line up.
+k::
+       Move cursor one line down.
+PgUp::
+b::
+-::
+       Move cursor one page up.
+PgDown::
+Space::
+       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
+
+[[refspec]]
+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  <<history-commands, "History 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 README
+
+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
+
+NOTE: For the main view, avoiding ambiguity will in some cases require 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"
+
+NOTE: If you want to avoid having to quote dates containing spaces you can use
+"." instead, e.g. `--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
+
+include::BUGS[]
+
+Copyright
+---------
+
+Copyright (c) 2006 Jonas Fonseca <fonseca@diku.dk>
+
+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.
+
+References and Related Tools
+----------------------------
+
+include::SITES[]
+
+Git porcelains:
+
+ - link:http://www.kernel.org/pub/software/scm/git/docs/[git],
+ - link:http://www.kernel.org/pub/software/scm/cogito/docs/[Cogito]
+
+Other git repository browsers:
+
+ - gitk(1)
+ - qgit(1)
+ - gitview(1)

diff --git a/tig.c b/tig.c
index e5f1ef1fdda71fce06da320705ae914dc1b955eb..e7deb2ec1d1ce423c1a1117527fbe487c91ac86a 100644 (file)
--- a/tig.c
+++ b/tig.c
@@ -417,45 +417,12 @@ parse_options(int argc, char *argv[])
        }
 
        if (!isatty(STDIN_FILENO)) {
-               /**
-                * 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
-                **/
                opt_request = REQ_VIEW_PAGER;
                opt_pipe = stdin;
 
        } else if (i < argc) {
                size_t buf_size;
 
-               /**
-                * 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.
-                *
-                * NOTE: If you specify options for the main view, you should
-                * not use the `--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 <<refspec, "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.
-                **/
-
                if (opt_request == REQ_VIEW_MAIN)
                        /* XXX: This is vulnerable to the user overriding
                         * options required for the main view parser. */
@@ -486,23 +453,6 @@ parse_options(int argc, char *argv[])
 /**
  * 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).
@@ -512,20 +462,6 @@ parse_options(int argc, char *argv[])
        "git ls-remote . 2>/dev/null"
 
 /**
- * [[history-commands]]
- * History 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.
@@ -848,23 +784,9 @@ load_options(void)
 }
 
 
-/**
+/*
  * The viewer
- * ----------
- * The display consists of a status window on the last line of the screen and
- * one or more views. The default is to only show one view at the time but it
- * is possible to split both the main and log view to also show the commit
- * diff.
- *
- * If you are in the log view and press 'Enter' when the current line is a
- * commit line, such as:
- *
- *     commit 4d55caff4cc89335192f3e566004b4ceef572521
- *
- * You will split the view so that the log view is displayed in the top window
- * and the diff view in the bottom window. You can switch between the two
- * views by pressing 'Tab'. To maximize the log view again, simply press 'l'.
- **/
+ */
 
 struct view;
 struct view_ops;
@@ -878,18 +800,7 @@ static unsigned int current_view;
 
 #define displayed_views()      (display[1] != NULL ? 2 : 1)
 
-/**
- * Current head and commit ID
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~
- * The viewer keeps track of both what head and commit ID you are currently
- * viewing. The commit ID will follow the cursor line and change everytime time
- * you highlight a different commit. Whenever you reopen the diff view it
- * will be reloaded, if the commit ID changed.
- *
- * The head ID is used when opening the main and log view to indicate from
- * what revision to show history.
- **/
-
+/* Current head and commit ID */
 static char ref_commit[SIZEOF_REF]     = "HEAD";
 static char ref_head[SIZEOF_REF]       = "HEAD";
 
@@ -947,35 +858,6 @@ static struct view_ops main_ops;
 #define VIEW_(id, name, ops, ref) \
        VIEW_STR(name, TIG_##id##_CMD,  TIG_##id##_CMD, ref, ops)
 
-/**
- * Views
- * ~~~~~
- * 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.
- **/
 
 static struct view views[] = {
        VIEW_(MAIN,  "main",  &main_ops,  ref_head),
@@ -1019,21 +901,6 @@ redraw_view(struct view *view)
 }
 
 
-/**
- * Title windows
- * ~~~~~~~~~~~~~
- * Each view has a title window which shows the name of the view, current
- * commit ID if available, and where the view is positioned:
- *
- *     [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
- *
- * By default, the title of the current view is highlighted using bold font.
- * For long loading views (taking over 3 seconds) the time since loading
- * started will be appended:
- *
- *     [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
- **/
-
 static void
 update_view_title(struct view *view)
 {
@@ -2085,11 +1952,9 @@ static struct view_ops main_ops = {
 };
 
 
-/**
- * KEYS
- * ----
- * Below the default key bindings are shown.
- **/
+/*
+ * Keys
+ */
 
 struct keymap {
        int alias;
@@ -2097,74 +1962,21 @@ struct keymap {
 };
 
 static struct keymap keymap[] = {
-       /**
-        * 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.
-        **/
+       /* View switching */
        { 'm',          REQ_VIEW_MAIN },
        { 'd',          REQ_VIEW_DIFF },
        { 'l',          REQ_VIEW_LOG },
        { 'p',          REQ_VIEW_PAGER },
        { 'h',          REQ_VIEW_HELP },
 
-       /**
-        * View manipulation
-        * ~~~~~~~~~~~~~~~~~
-        * q::
-        *      Close view, if multiple views are open it will jump back to the
-        *      previous view in the view stack. If it is the last open view it
-        *      will quit. Use 'Q' to quit all views at once.
-        * Enter::
-        *      This key is "context sensitive" depending on what view you are
-        *      currently in. When in log view on a commit line or in the main
-        *      view, split the view and show the commit diff. In the diff view
-        *      pressing Enter will simply scroll the view one line down.
-        * Tab::
-        *      Switch to next view.
-        * Up::
-        *      This key is "context sensitive" and will move the cursor one
-        *      line up. However, uf you opened a diff view from the main view
-        *      (split- or full-screen) it will change the cursor to point to
-        *      the previous commit in the main view and update the diff view
-        *      to display it.
-        * Down::
-        *      Similar to 'Up' but will move down.
-        **/
+       /* View manipulation */
        { 'q',          REQ_VIEW_CLOSE },
        { KEY_TAB,      REQ_VIEW_NEXT },
        { KEY_RETURN,   REQ_ENTER },
        { KEY_UP,       REQ_PREVIOUS },
        { KEY_DOWN,     REQ_NEXT },
 
-       /**
-        * Cursor navigation
-        * ~~~~~~~~~~~~~~~~~
-        * j::
-        *      Move cursor one line up.
-        * k::
-        *      Move cursor one line down.
-        * PgUp::
-        * b::
-        * -::
-        *      Move cursor one page up.
-        * PgDown::
-        * Space::
-        *      Move cursor one page down.
-        * Home::
-        *      Jump to first line.
-        * End::
-        *      Jump to last line.
-        **/
+       /* Cursor navigation */
        { 'k',          REQ_MOVE_UP },
        { 'j',          REQ_MOVE_DOWN },
        { KEY_HOME,     REQ_MOVE_FIRST_LINE },
@@ -2175,44 +1987,13 @@ static struct keymap keymap[] = {
        { 'b',          REQ_MOVE_PAGE_UP },
        { '-',          REQ_MOVE_PAGE_UP },
 
-       /**
-        * 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.
-        **/
+       /* Scrolling */
        { KEY_IC,       REQ_SCROLL_LINE_UP },
        { KEY_DC,       REQ_SCROLL_LINE_DOWN },
        { 'w',          REQ_SCROLL_PAGE_UP },
        { 's',          REQ_SCROLL_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
-        **/
+       /* Misc */
        { 'Q',          REQ_QUIT },
        { 'z',          REQ_STOP_LOADING },
        { 'v',          REQ_SHOW_VERSION },
@@ -2785,105 +2566,8 @@ main(int argc, char *argv[])
 }
 
 /**
- * [[refspec]]
- * 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  <<history-commands, "History 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 README
- *
- * 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
- *
- * NOTE: For the main view, avoiding ambiguity will in some cases require
- * 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"
- *
- * NOTE: If you want to avoid having to quote dates containing spaces you
- * can use "." instead, e.g. `--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
- *
  * include::BUGS[]
  *
- * include::SITES[]
- *
  * COPYRIGHT
  * ---------
  * Copyright (c) 2006 Jonas Fonseca <fonseca@diku.dk>
@@ -2903,4 +2587,8 @@ main(int argc, char *argv[])
  *  - gitk(1)
  *  - qgit(1)
  *  - gitview(1)
+ *
+ * Sites:
+ *
+ * include::SITES[]
  **/