Function: time-stamp

time-stamp is an autoloaded, interactive and byte-compiled function defined in time-stamp.el.gz.

Signature

(time-stamp)

Documentation

Update any time stamp string(s) in the buffer.

This function looks for a time stamp template and updates it with the current date, time, and/or other info.

The template, which you manually create on one of the first 8 lines of the file before running this function, by default can look like one of the following (your choice):
      Time-stamp: <>
      Time-stamp: " "
This function writes the current time between the brackets or quotes, by default formatted like this:
      Time-stamp: <2020-08-07 17:10:21 gildea>

Although you can run this function manually to update a time stamp once, usually you want automatic time stamp updating.

A time stamp can be automatically updated with current information every time you save a file. To enable time-stamping for all files, customize option before-save-hook or add this line to your init file:
    (add-hook 'before-save-hook 'time-stamp)

To enable automatic time-stamping for only a specific file, add this line to a local variables list near the end of the file:
    eval: (add-hook 'before-save-hook 'time-stamp nil t)

If the file has no time-stamp template, this function does nothing.

You can set time-stamp-pattern in a file's local variables list to customize the information in the time stamp and where it is written.

The time stamp is updated only if time-stamp-active is non-nil.

View in manual

Probably introduced at or before Emacs version 20.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/time-stamp.el.gz
;;;###autoload(put 'time-stamp-pattern 'safe-local-variable 'stringp)



;;;###autoload
(defun time-stamp ()
  "Update any time stamp string(s) in the buffer.
This function looks for a time stamp template and updates it with
the current date, time, and/or other info.

The template, which you manually create on one of the first 8 lines
of the file before running this function, by default can look like
one of the following (your choice):
      Time-stamp: <>
      Time-stamp: \" \"
This function writes the current time between the brackets or quotes,
by default formatted like this:
      Time-stamp: <2020-08-07 17:10:21 gildea>

Although you can run this function manually to update a time stamp
once, usually you want automatic time stamp updating.

A time stamp can be automatically updated with current information
every time you save a file.  To enable time-stamping for all files,
customize option `before-save-hook' or add this line to your init file:
    (add-hook \\='before-save-hook \\='time-stamp)

To enable automatic time-stamping for only a specific file, add
this line to a local variables list near the end of the file:
    eval: (add-hook \\='before-save-hook \\='time-stamp nil t)

If the file has no time-stamp template, this function does nothing.

You can set `time-stamp-pattern' in a file's local variables list
to customize the information in the time stamp and where it is written.

The time stamp is updated only if `time-stamp-active' is non-nil."
  (interactive)
  (let ((line-limit time-stamp-line-limit)
	(ts-start time-stamp-start)
	(ts-format time-stamp-format)
	(ts-end time-stamp-end)
	(ts-count time-stamp-count)
	(format-lines 0)
	(end-lines 1)
	(start nil)
	search-limit)
    (if (stringp time-stamp-pattern)
	(progn
	  (string-match "\\`\\(\\(-?[0-9]+\\)/\\)?\\([^%]+\\)?\\(\\(%[-.,:@+_ #^()0-9]*[A-Za-z%][^%]*\\)*%[-.,:@+_ #^()0-9]*[A-Za-z%]\\)?\\([^%]+\\)?\\'" time-stamp-pattern)
	  (and (match-beginning 2)
	       (setq line-limit
		     (string-to-number (match-string 2 time-stamp-pattern))))
	  (and (match-beginning 3)
	       (setq ts-start (match-string 3 time-stamp-pattern)))
	  (and (match-beginning 4)
	       (not (string-equal (match-string 4 time-stamp-pattern) "%%"))
	       (setq ts-format (match-string 4 time-stamp-pattern)))
	  (and (match-beginning 6)
	       (setq ts-end (match-string 6 time-stamp-pattern)))))
    (cond ((not (integerp line-limit))
	   (setq line-limit 8)
	   (message "time-stamp-line-limit is not an integer")
	   (sit-for 1)))
    (cond ((not (integerp ts-count))
	   (setq ts-count 1)
	   (message "time-stamp-count is not an integer")
	   (sit-for 1))
	  ((< ts-count 1)
	   ;; We need to call time-stamp-once at least once
	   ;; to output any warnings about time-stamp not being active.
	   (setq ts-count 1)))
    ;; Figure out what lines the end should be on.
    (if (stringp ts-format)
	(let ((nl-start 0))
	  (while (string-match "\n" ts-format nl-start)
	    (setq format-lines (1+ format-lines) nl-start (match-end 0)))))
    (let ((nl-start 0))
      (while (string-match "\n" ts-end nl-start)
	(setq end-lines (1+ end-lines) nl-start (match-end 0))))
    ;; Find overall what lines to look at
    (save-excursion
      (save-restriction
	(widen)
	(cond ((> line-limit 0)
	       (goto-char (setq start (point-min)))
	       (forward-line line-limit)
	       (setq search-limit (point)))
	      ((< line-limit 0)
	       (goto-char (setq search-limit (point-max)))
	       (forward-line line-limit)
	       (setq start (point)))
	      (t			;0 => no limit (use with care!)
	       (setq start (point-min))
	       (setq search-limit (point-max))))))
    (while (and start
		(< start search-limit)
		(> ts-count 0))
      (setq start (time-stamp-once start search-limit ts-start ts-end
				   ts-format format-lines end-lines))
      (setq ts-count (1- ts-count))))
  nil)