The browser-history web page

This page describes the utility browser-history, a client-side X daemon maintaining a browser-independent global history of all the web sites you visited.

On this page ( you will find:


Browser-history came from the will to overcome a Netscape bug: there was no global history, and if you close a window, its whole history is lost. For people browsing lots of sites, having a possibility to track back where one has been before means that you dont have to put everything in your bookmarks file. If you are not sure if a site may be worth remebering, don't add it in your bookmarks. If you need it later, just browse your history files.

Later, it came to our minds that this also could be a valuable add-on to people writing experimental browsers, so they dont have to add this functionality to their browser itself, and to users able thus to track their web history regardless of the browser they used.

Browser-history is a small and efficient daemon. Real user services could be built on top of the log files it maintains for more possibilities (graphical representation, advanced search options, collective histories). It can be seen as a quick-and-dirty hack wrt to the general solution of using a personal proxy to provide this history and housekeeping facilities. But in the meantime, it is easy to use and it works.

And now that Netscape has a semi-decent history, browser-history is still valuable, as it is difficult to search in the netscape history, its file format is not defined, and entries expire after some time.


Colas Nahaboo, Koala project.

License: Open Source

The X distribution license: you can do everything with this code (selling it, modifying it), except suing me or using my name in your advertisements, or expecting any kind of support or guarantee.

Quick usage guide

Just run the program each time you launch your X server. Just add the following line into your .xinitrc or equivalent startup file:

browser-history &

Installation guide

Compilation is straigthforward. See Makefile, but normally, just typing make is sufficient. It only uses Xlib and Xmu, not Xt. You must just install the resulting binary "browser-history" somewhere in your PATH. I tested it on linux, DEC alpha OSF/1, SGI, sun solaris 5.5, sun sunos 4.1.3.

Sample result

You can then open with your browser the URL:
(replace $HOME by your homedir), and you will see:

Tuesday 28 May 1996

Colas's home page 1996/05/28-08:38:34 0x6004a64
Jean-Michel's home page 1996/05/28-08:42:07 0x6004a64
phk's home page 1996/05/28-10:22:32 0x6004a64

You can click on the listed URLs to go back to them, each entry is listed with the page name in bold, followed by the clickable URL, then the date and time you loaded it, and the X ID of the browser window.

An horizontal rule indicates that at least one hour separates two entries. A file holds one week of history, past weeks are accessibles via links at the top of the page.

Reference Manual

browser-history logs in ~/.browser-history/history-log.html all the URLs you went through. You can then browse the log under Netscape or other browsers via the URL: file:~/.browser-history/history-log.html (replace the ~ by your home directory)

browser-history tracks automagically all already present browser windows, and all new ones created in the future. This program has no user interface. It just appens information to a log file in html format so you can browse it through a web browser. If more that one hour has passed since last entry, it draws an horizontal lines, and adds H1 headers to delimit new days. Each week (sunday mornings), it archives the week history, compresses it by gzip (that you must have in your path), and starts a new history with links to the older ones. To make room you can just remove the obsolete history files.

This version works with Netscape, Arena and Amaya.

URLs can be excluded from logging by putting them, one per line in the file ~/.browser-history/history-log.exclude. Then, if an URL begins with a line from this file, it is not logged. In this file, empty lines or lines beginning by # are comments This file is read once at startup, and re-read when receiving the signal 1. e.g:

    # We exclude local files
    # Exclude search engines...

browser-history maintains a hidden window on the X display, whose ID is given by the property BROWSER_HISTORY on the root window. If this window is killed, it quits gracefully. On this sub-window the following properties are maintained:

You can customise the header of the newly created weekly log files by putting the header you want to use as an header.html file in the ~/browser-history directory. The default header is the first part of a newly generated file upto the line:

<!-- EndOfHeader -->

When browser-history is run, it looks if another one is running, and by default it kills the previous one if it is an older version. Otherwise, it the new one is the same version number or older, it just aborts.


All options can be given by their first letter: you can specify either -verbose or -v, but you cannot group options, e.g. you must say -v -k, but not -vk

-display display_name
Specifies X display, otherwise contents of $DISPLAY is used
outputs information on what it is doing. useful for debug.
prints version number and exit.
-logdir directory
which directory to store files into? defaults to ~/.browser-history
-gzip gzip_filename
the complete path to the gzip compressor. Defaults to gzip.
E.g: -gzip /usr/gnu/bin/gzip
-seconds delay
if two entries are made are more than delay seconds apart, an horizontal rule will separate them, else just a simple line break. Defaults to one hour (3600).
If there is an already running browser-history on the display, kills it and take its place. Default is to replace it only if the version is older than ours.
If there is an already running browser-history on the display, aborts. Default is to replace it only if the version is older than ours.
If there is an already running browser-history on the display, kills it, then terminates immediately in all cases.
Never Grab the X Server, which might cause deadlocks while debugging, when browser-history or gdb tries to print on the grabbed xterm or emacs.

Specifications of the log files

A log file can have some decorative HTML to represent days, but each entry has the form: (the leading br can also be an hr)

<b>name</b> <a href="URL">URL</a> yyyy/mm/dd-hh:mn:ss <small>windowid</small>
where the following items are: Note: Before version 2.4, the 4 sub-parts were separated by newlines, but since 2.4, they are only blank-separated to ease searching for URL in log files via "grep".
Note:Before version 2.5, the year was stored in 2 digits. Now it is stored in 4 (or more :-) digits, to fix this Y2K bug
Note:Since version 2.6, you should skip the header by searching for the string <!-- EndOfHeader --> and parse entries till the end, the last one being possibly incomplete in case of concurrent update (you can check the LAST_POS property if you want to avoid this problem)
The logic is thus to parse log files made after mid-97 (v 2.4) is to open the log, and:
  1. Skip beginning up to string <!-- EndOfHeader -->
    If not found, skip to first <hr><p><h1>
  2. now position to next entry beginning with r> <b> at position A. If we cannot find one, we are done.
  3. verify that the entry is valid by checking that a string </small> exists at position B before the end of file
  4. process the entry that is being offsets A and B
  5. repeat last 2 steps

How to download it

By ftp on

Supported browsers

Currently supported browsers are:

How to add support in the browser

You can add support for browser-history in any browser. See for instance the description of the Arena client communication system.

Just add on each browser window a string X property named BROWSER_HISTORY_INFO (and type XA_STRING) of the form (C printf string below):

where the first %s is the current URL, and the second the document name.

IMPORTANT! This property MUST be present and MUST contain some value BEFORE mapping (managing) the window, for browser-history to detect it. Otherwise, your browser windows will be ignored. If this proves too difficult for you, you can make the detection of your browser windows built-in in browser-history, search the string BT_AMAYA and add cases for your browser, and send me the patches.

Example from arena: each time a new URL is visited, it triggers this function on the window displaying the document at the same time as it updates the X window title by a call to XStoreName(dpy, win, title).

void SetXProperties(	    /* sets info for browser-history on each new URL */
    Display *dpy,	    /* the X display */
    Window win,		    /* the main document display window */
    char *url,		    /* the URL being visited */
    char *title)	    /* the <TITLE> of the document */
    static Atom property_name = 0;
	                                    /* 13 is strlen("URL=0TITLE=00") */
    int v_size = strlen(title) + strlen(url) + 13;
    char *v = (char *) malloc(v_size);	/* or alloca, but dont call free */
    sprintf(v, "URL=%s%cTITLE=%s%c", url, 0, title, 0);
    if (!property_name)
	property_name = XInternAtom(dpy, "BROWSER_HISTORY_INFO", False);
    XChangeProperty(dpy, win, property_name, XA_STRING, 8, PropModeReplace,
			v, v_size);


History of changes, both to the browser-history program and to this page:
v2.8 - 24-Jul-2000
v2.7 - 20-Jul-2000
v2.6 - 08-Jun-2000
v2.5 - 06-Aug-1999
v2.4 - 24-Aug-97
Log entries are now on the same line, to ease grep searches in files.
v2.3 - 14-Feb-97
bugfix: on creating a new file on sundays, one some OSes (SunOs4+NFS), the list of previous histories was empty. Problem detected and fixed by Hubert CANON
v2.2 - 03-Oct-96
built-in support of the last Amaya version (new official editor+browser of the web consortium)
v2.1 - 13-Sep-96
you can add support to your browser without recompiling or restarting browser-history, see Supported browsers
new option -Version, prints version and exits.
v1.18 - 25-Jun-96
Past weeks stored most recent first instead of oldest first at top of history file.
v1.17 - 30-May-96
Works on SunOS and on pure BSD system, where you must add the compilation flag -DBSD or type "make bsd".
new option -DontGrab for debug.
v1.16 - 28-May-96
Works even if gzip is not installed, and gzip location settable by the new -gzip option
v1.14 - 28-May-96
No need anymore for a crontab-run shell script to add day names and week cleanups to the log.
Web page installed.
v1.6 - 03-May-96
Directory name changed to "~/.browser-history", was "~/.netscape-history" before...
v1.4 - 15-Feb-96
Arena implements supports too.
v1.1 - 01-Feb-96
First version, netscape only.

Back to table of contents