Function: org-clock-out

org-clock-out is an autoloaded, interactive and byte-compiled function defined in org-clock.el.gz.

Signature

(org-clock-out &optional SWITCH-TO-STATE FAIL-QUIETLY AT-TIME)

Documentation

Stop the currently running clock.

Throw an error if there is no running clock and FAIL-QUIETLY is nil. With a universal prefix, prompt for a state to switch the clocked out task to, overriding the existing value of org-clock-out-switch-to-state.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-clock.el.gz
;;;###autoload
(defun org-clock-out (&optional switch-to-state fail-quietly at-time)
  "Stop the currently running clock.
Throw an error if there is no running clock and FAIL-QUIETLY is nil.
With a universal prefix, prompt for a state to switch the clocked out task
to, overriding the existing value of `org-clock-out-switch-to-state'."
  (interactive "P")
  (catch 'exit
    (when (not (org-clocking-p))
      (setq global-mode-string
	    (delq 'org-mode-line-string global-mode-string))
      (org-clock-restore-frame-title-format)
      (force-mode-line-update)
      (if fail-quietly (throw 'exit t) (user-error "No active clock")))
    (let ((org-clock-out-switch-to-state
	   (if switch-to-state
	       (completing-read "Switch to state: "
				(with-current-buffer
				    (marker-buffer org-clock-marker)
				  org-todo-keywords-1)
				nil t "DONE")
	     org-clock-out-switch-to-state))
	  (now (org-current-time org-clock-rounding-minutes))
	  ts te s h m remove)
      (setq org-clock-out-time (or at-time now))
      (save-excursion ; Do not replace this with `with-current-buffer'.
	(with-no-warnings (set-buffer (org-clocking-buffer)))
	(save-restriction
	  (widen)
	  (goto-char org-clock-marker)
	  (forward-line 0)
	  (if (and (looking-at (concat "[ \t]*" org-keyword-time-regexp))
		   (equal (match-string 1) org-clock-string))
	      (setq ts (match-string 2))
	    (if fail-quietly (throw 'exit nil) (error "Clock start time is gone")))
	  (goto-char (match-end 0))
	  (delete-region (point) (line-end-position))
          (org-fold-core-ignore-modifications
            (insert-and-inherit "--")
            (setq te (org-insert-timestamp (or at-time now) 'with-hm 'inactive))
            (setq s (org-time-convert-to-integer
                     (time-subtract
                      (org-time-string-to-time te)
                      (org-time-string-to-time ts)))
                  h (floor s 3600)
                  m (floor (mod s 3600) 60))
            (insert-and-inherit " => " (format "%2d:%02d" h m))
            (move-marker org-clock-marker nil)
            (move-marker org-clock-hd-marker nil)
            ;; Possibly remove zero time clocks.
            (when (and org-clock-out-remove-zero-time-clocks
                       (= 0 h m))
              (setq remove t)
              (delete-region (line-beginning-position)
                             (line-beginning-position 2)))
            (org-clock-remove-empty-clock-drawer))
	  (when org-clock-mode-line-timer
	    (cancel-timer org-clock-mode-line-timer)
	    (setq org-clock-mode-line-timer nil))
	  (when org-clock-idle-timer
	    (cancel-timer org-clock-idle-timer)
	    (setq org-clock-idle-timer nil))
	  (setq global-mode-string
		(delq 'org-mode-line-string global-mode-string))
	  (org-clock-restore-frame-title-format)
	  (when org-clock-out-switch-to-state
	    (save-excursion
	      (org-back-to-heading t)
	      (let ((org-clock-out-when-done nil))
		(cond
		 ((functionp org-clock-out-switch-to-state)
		  (let ((case-fold-search nil))
		    (looking-at org-complex-heading-regexp))
		  (let ((newstate (funcall org-clock-out-switch-to-state
					   (match-string 2))))
		    (when newstate (org-todo newstate))))
		 ((and org-clock-out-switch-to-state
		       (not (looking-at
                             (concat
                              org-outline-regexp "[ \t]*"
			      org-clock-out-switch-to-state
			      "\\(?:[ \t]\\|$\\)"))))
		  (org-todo org-clock-out-switch-to-state))))))
	  (force-mode-line-update)
	  (message (if remove
		       "Clock stopped at %s after %s => LINE REMOVED"
		     "Clock stopped at %s after %s")
		   te (org-duration-from-minutes (+ (* 60 h) m)))
          (unless (org-clocking-p)
	    (setq org-clock-current-task nil))
          (setq org-clock-out-removed-last-clock remove)
          (run-hooks 'org-clock-out-hook)
          ;; Add a note, but only if we didn't remove the clock line.
          (when (and org-log-note-clock-out (not remove))
            (org-add-log-setup
	     'clock-out nil nil nil
	     (concat "# Task: " (org-get-heading t) "\n\n"))))))))