Color Options:
*timestamp.vim* Plugin for automated time stamping
Description:~
When a file is written, and the filename matches |timestamp_automask|, this
plugin will search the first and last |timestamp_modelines| lines of your
file. If it finds the regexp |timestamp_regexp| then it will replace it with a
timestamp. The timestamp is computed by first doing a |token_substitution| on
|timestamp_rep| and passing the result to |strftime()|.
The plugin tries to stay out of your way, and make the change as transparent
as possible. All your history (search, command, etc) and the jump list is
unaltered, except the undo history (which contains an additional change).
All the default variables and actions can be changed by buffer / global vim
variables. See |timestamp_examples| for two simple examples.
The plugin and its documentation file can be installed as described under
|add-global-plugin| and |add-local-help|. Do not forget to run |:helptags|.
------------------------------------------------------------------------------
Options and Specifications:~
1. Timestamp Regexp format: *timestamp_regexp*
If the regexp |timestamp_regexp| is found in the first and last
|timestamp_modelines| lines of your file it is replaced by a timestamp (see
|timestamp_rep|).
Default: \v\C%(<%(Last %([cC]hanged?|modified)|Modified)\s*:\s+)@<=\a+ \d{2} \a+ \d{4} \d{2}:\d{2}:\d{2} [AP]M ?%(\a+)?|TIMESTAMP
To change this value, either set g:timestamp_regexp in your {.vimrc} or set
b:timestamp_regexp for the buffer in question. NOTE: This global variable must
be set before the plugin is loaded. HOWEVER the buffer local variable can be
set at any time.
NOTE: Forward slashes are automatically escaped.
The default value will EITHER match 'TIMESTAMP' or a time (in the format of
strftime("%c")) FOLLOWED by a 'Last changed:' or 'Last modified:'. For
instance, if you create a new file and want to stamp it with a creation date
and a last modified date, make the first few lines: >
When you first write the file, these lines will change to: >
On subsequent writes of the file, the first line will remain unchanged and the
second will be stamped with the time of writing.
NOTE: The first line (beginning with "Created:") is optional.
NOTE: If you find that on subsequent writes of the file, the second line is
also unchanged, it is probably because the time returned by strftime is NOT is
the format above. Common reasons for this are if there is a leading 0 or
timezone missing, or if the day / month in your language has accented
characters. If you are using version 1.11 and higher and still have this
problem, please report it to me. As a temporary fix, you can put the line >
in your .vimrc. This however has the disadvantage of eating all the text after
the colon in any timestamp line.
NOTE: Windows Users. If you find that the timezone is in full form instead of
abbriviated (i.e. 'Chicago Standard Time' instead of 'CST') then look at >
for details on how to change it (thanks to Shishir Ramam for pointing this
out). If you preffer using the full form timezone, then add the line >
to your .vimrc. You could also just remove the '%Z' from |timestamp_rep| if
you don't want the timezone at all.
------------------------------------------------------------------------------
2. Timestamp Replacement format: *timestamp_rep*
The timestamp is computed by first doing a |token_substitution| on
|timestamp_rep| and passing the result to |strftime()|.
Default: '%a %d %b %Y %I:%M:%S %p %Z'
[On Linux systems this is equivalent to the preferd date and time
representation for the current locale.]
To change this value, either set g:timestamp_rep in your {.vimrc} or set
b:timestamp_rep for the buffer in question. NOTE: This global variable must be
set before the plugin is loaded. HOWEVER the buffer local variable can be set
at any time.
NOTE: Forward slashes are automatically escaped.
------------------------------------------------------------------------------
TOKEN SUBSTITUTION *token_substitution*
Before being passed to |strftime()|, |timestamp_rep| undergoes the following
substitutions:
Token Substitution~
#f |timestamp_filename|
#h |timestamp_hostname|
#H |timestamp_Hostname|
#u |timestamp_username|
#i |timestamp_userid|
*timestamp_filename*
The "#f" token is replaced by the filename of the current buffer (without
leading path components).
*timestamp_Hostname*
The #H token is replaced by the full hostname of the current vim process.
If the variable |timestamp_UseSystemCalls| is set, the default value of
the hostname will be obtained from the output of the command 'hostname
-f'. If that fails, (or |timestamp_UseSystemCalls| is not set), the value
of the $HOSTNAME or $HOST variables will be used. If they are both empty,
then the value of the |hostname()| function will be used.
If the default value is incorrect, or you want to use a different value,
simply set the global variable 'g:timestamp_Hostname', or the buffer local
variable 'b:timestamp_Hostname' to the desired value. NOTE: This global
variable must be set before the plugin is loaded, however the buffer local
variable can be set at any time.
*timestamp_hostname*
The #h is the same as the #H token, but with the domain name stripped.
User defined values can be specified using the variables
g:timestamp_hostname or b:timestamp_hostname. See the note above about
global / local variables.
*timestamp_username*
The #u token will be replaced by the user name.
The default value of the user name will be obtained from $USER or $LOGNAME
environment variables. If both are empty (undefined) and the variable
|timestamp_UseSystemCalls| is set, then the output of the command 'id -un'
will be used.
If the default value is incorrect, or you want to use a different value,
simply set the global variable 'g:timestamp_username', or the buffer local
variable 'b:timestamp_username' to the desired value. NOTE: The global
variable must be set before the plugin is loaded, however the buffer local
variable can be set at any time.
*timestamp_userid*
The #i token will be replaced by the userid.
The default vaule is obtained from the "id -un" command. If that fails,
the default value is obtained by searching the password file for the
username obtained above. NOTE: This is done only when the vim variable
|timestamp_UseSystemCalls| is set.
A different value can be specified by setting the global variable
g:timestamp_userid or the buffer local variable b:timestamp_userid to the
desired value. NOTE: The global variable must be set before the plugin is
loaded, however the buffer local variable can be set at any time. NOTE:
When looking up the user in the password file, the buffer local variable
b:timestamp_username is ignored.
*timestamp_UseSystemCalls*
If the variable |timestamp_UseSystemCalls| is set, then system calls are
made to determine the default values of |timestamp_Hostname|,
|timestamp_userid| and |timestamp_username|. These generally cause about a
half a second delay (on my super slow AMD K6-2) in the plugin
initialisation, hence they are disabled by default. If you would like this
plugin to use system calls to obtain the default values of Hostname,
username and userid, then set the variable |timestamp_UseSystemCalls| in
your {.vimrc}. NOTE: The environment variables / corresponding global
variables will still be read when this variable is unset. Only the system
commands (like 'id -un') will not be made.
If you define any of the global variables |timestamp_Hostname|,
|timestamp_username| or |timestamp_userid|, then the corresponding system
call will not be made (regardless of the value of
|timestamp_UseSystemCalls|). Thus if you want to avoid only some
particular system calls, you can do it by setting the corresponding global
variable.
NOTE: In version 1.17 and up, these initialisations are no longer done on
Vim startup, but done the first time the plugin is actually needed. So
regardless of the global defaults, Vim startup will still be fast as
always. On my ancient slow home computer (AMD K6-2 500mHz) avoiding the
system calls saves me about half a second the first time I write a file.
If you use these features, and want the system defaults, half a second per
vim session might not be too much of a price to pay.
------------------------------------------------------------------------------
4. Timestamp Auto command Mask *timestamp_automask*
By default, the plugin installs an "autocommand BufWrite" for all files. So it
uses '*' as {pat} (see |:autocmd|). The user can overrule this behaviour by
defining g:timestamp_automask with the desired value, e.g.: >
to limit timestamping to html files. NOTE: This global variable has to be set
BEFORE the plugin is loaded.
NOTE: If you compiled Vim without autocommands, this plugin will not work.
------------------------------------------------------------------------------
5. timestamp_modelines *timestamp_modelines*
The number of lines searched for the |timestamp_regexp| is controlled by the
|timestamp_modelines| variable. By default this will be equal to the
'modelines' option. To specify a different value, set the global vim variable
'g:timestamp_modelines'. NOTE: This global variable has to be set BEFORE the
plugin is loaded. HOWEVER the buffer local variable can be set at any time.
If this is set to to '%' all lines in the file will be searched for the regexp
|timestamp_regexp|. NOTE: This may be more than you want.
------------------------------------------------------------------------------
6. Examples: *timestamp_examples*
1. No case matching, short format timestamps: >
< Result: >
< 2. Match case, with filename, username and hostname in html comments: >
< Result: >
------------------------------------------------------------------------------
7. Change History *timestamp_history*
Version 1.18:~
Made timestamping work with zipped files (by using the |BufWritePre|
autocommand, instead of |BufWrite|). Also preserves your jump / changelist.
Version 1.17:~
Reduce Vim's initial load time significantly. On my system, Vim with
timestamp-1.16 loads in about 1.1 seconds. With timestamp-1.17, it loads in
only 0.3 seconds! The system calls to initialise the uid / username were
taking time. Calls to these functions have been disabled by default, and
further postponed untill the are necessary (and not on Vim startup). These
calls can be enabled by setting the variable |timestamp_UseSystemCalls|.
Version 1.16:~
Made all g:timestamp_* variables also available as buffer local variables
except for g:timestamp_automask. Thanks to Lars Wilke for doing this. Also
fixed default values for |timestamp_hostname|, |timestamp_Hostname|,
|timestamp_userid| and |timestamp_username|. Thanks again to Lars Wilke for
testing on various platforms.
Version 1.15:~
Modified the default timestamp regexp to support timestamps in other
languages by default. This only works if the day and month names in your
language do not use accented characters. If accented characters are present
you should set the default timestamp regexp in your .vimrc. English users
should not notice any difference.
Version 1.14:~
Now also works in compatible mode.
Version 1.13:~
Removed unwanted code for preserving cursor location. With use of setline
and getline this is no longer necessary. A bug caused timestamp.vim to make
changes in all lines in the |timestamp_modelines| range. Corrected the code
so that now changes are made only when there is a timestamp in a particular
line. This makes undoing changes a lot easier.
Version 1.12:~
Some Micro$oft machines don't support the timezone ('%Z'). Made the timezone
optional in the default settings. The script (with default settings) should
now work on both Linux / Window$ machines. Thanks to Krall Ed-P27726 for
testing this.
Version 1.11:~
Minor bug fix. The format of strftime("%c") is not standard among all
systems / locales. Changed the default value of "timestamp_rep" from "%c" to
the full expanded version. This should be more robust.
Version 1.1:~
Does not modify any marks or the search history list. Tries to make
timestamping as "transparent" as possible.
Version 1.0:~
Original fork of "timstamp.vim". See |timestamp_differences| for a list of
differences.
------------------------------------------------------------------------------
8. Differences From Timstamp: *timestamp_differences*
This script is based on "timstamp.vim" originally written by Guido Van Hoecke
<Guido@VanHoecke.org>. There are many differences:
1. Note the extra E in the name (timEstamp).
2. Some bug fixes.
3. Splits the pattern and replacement into two separate variables.
4. Allows buffer local variables to replace the timestamp controls.
5. Removed support for multiple timestamps (I thought this was wasteful,
besides allowing buffer local variables to control timestamps makes this
unnecessary. Timestamps for particular filetypes can be set by buffer
local variables in filetype plugins)
6. timstamp_* variables are no longer present. Use |timestamp_regexp| for
the search pattern, and |timestamp_rep| for the replacement.
|timestamp_rep| is substituted for filenames and then passed to
|strftime()|.
7. Removed the language setting. |strftime()| should provide this in your
favourite language (provided your locale is set correctly)
8. By default the timestamp regexps will NOT match everything after a
"Last changed" or "Last modified". It will match exactly a time after
each of those expressions! Hence a line like >
< will get replaced with >
< Note that the final </i> is left unchanged!
9. To create a new timestamp in a file, put a line of the form
Last changed: TIMESTAMP (other optional stuff)
in your file. The TIMESTAMP will get replaced with a timestamp. This
only works with the default regexp. If you change that you're on your
own
10. To check the entire file, set timestamp_modelines to '%' (instead of the
unintuitive '$' as before)
------------------------------------------------------------------------------
>