In a Lisp function, how do I instruct org to automatically insert a timestamp with today's date?

I found the function org-insert-time-stamp, but I don't know how to provide an argument for it that will return today's date.

The documentation for the function says:

(org-insert-time-stamp TIME &optional WITH-HM INACTIVE PRE POST EXTRA)  

...but I don't see where to find documentation about what TIME &optional WITH-HM INACTIVE PRE POST EXTRA means or how to specify these in a function.

And here's the function I'm trying to write:

(defun org-today-heading-and-clock-in ()
  "Insert a new heading with today's date, and then clock in."
  (org-insert-time-stamp (today))

3 Answers 3


With a bit of guesswork:

(org-insert-time-stamp (current-time))
  • Thank you. In general, how do I find out what format a function's arguments need to be in, aside from guesswork? Commented Jan 10, 2015 at 20:18
  • 1
    Just jump to the definition. For instance, time is used by format-time-string. And that doc explains more clearly what time is.
    – abo-abo
    Commented Jan 10, 2015 at 20:25
  • 2
    I disagree with @abo-abo. This is a doc bug. The doc string should either refer you to function format-time-string, saying that the TIME arg is of the same kind, or it should say what the doc string of format-time-string says about TIME: "TIME is specified as (HIGH LOW USEC PSEC), as returned by current-time' or file-attributes'. The obsolete form (HIGH . LOW) is also still accepted."
    – Drew
    Commented Jan 10, 2015 at 21:02
  • Added to the docstring: See `format-time-string' for the format of TIME
    – abo-abo
    Commented Jan 10, 2015 at 21:29
  • 3
    @grettke, it's not C-x i by default, it's C-c .
    – nanny
    Commented Jan 13, 2015 at 14:29

I am using the following two functions with different timestamp formats. The number of digits to be used in year ie 2015 or 15 and hours, minutes, seconds etc can also be specified.

(defun now ()
  "Insert string for the current time formatted like '2:34 PM' or 1507121460"
  (interactive)                 ; permit invocation in minibuffer
  ;;(insert (format-time-string "%D %-I:%M %p")))
  ;;(insert (format-time-string "%02y%02m%02d%02H%02M%02S")))
  (insert (format-time-string "%02y%02m%02d%02H%02M")))

(defun today ()
  "Insert string for today's date nicely formatted in American style,
  e.g. Sunday, September 17, 2000 or standard 17-09-2000."
  (interactive)       ; permit invocation in minibuffer
  ;;(insert (format-time-string "%A, %B %e, %Y")))
  (insert (format-time-string "%d-%m-%y")))

I get a time stamp using {{{date}}}

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.