From 1f3b21b50e249c91cf9f0f11b9f6a29923154787 Mon Sep 17 00:00:00 2001
From: Dyson Simmons <dysonsimmons@gmail.com>
Date: Sat, 11 May 2019 13:33:07 +0100
Subject: [PATCH] Add description as comment in crontab

Adds a desc to a job that will be output as a comment above the cron
entry in the crontab. It supports single line and multiline
descriptions.
---
 README.md                           | 20 ++++++++++++++++++++
 lib/whenever/job.rb                 |  3 ++-
 lib/whenever/job_list.rb            |  1 +
 test/functional/output_desc_test.rb | 25 +++++++++++++++++++++++++
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 test/functional/output_desc_test.rb

diff --git a/README.md b/README.md
index 9a284a60..c3ff2442 100644
--- a/README.md
+++ b/README.md
@@ -175,6 +175,26 @@ every 3.hours do
 end
 ```
 
+### Adding comments to crontab
+
+A description can be added to a job that will be included in the crontab as a comment above the cron entry.
+
+Example: A single line description:
+
+```ruby
+every 1.hours, desc: "My job description" do
+  command "/usr/bin/my_great_command"
+end
+```
+
+Example: A multi line description:
+
+```ruby
+every 1.hours, desc: "My job description\nhas multiple lines" do
+  command "/usr/bin/my_great_command"
+end
+```
+
 ### Capistrano integration
 
 Use the built-in Capistrano recipe for easy crontab updates with deploys. For Capistrano V3, see the next section.
diff --git a/lib/whenever/job.rb b/lib/whenever/job.rb
index 2dad8329..0d0a660f 100644
--- a/lib/whenever/job.rb
+++ b/lib/whenever/job.rb
@@ -2,7 +2,7 @@
 
 module Whenever
   class Job
-    attr_reader :at, :roles, :mailto
+    attr_reader :at, :roles, :mailto, :desc
 
     def initialize(options = {})
       @options = options
@@ -11,6 +11,7 @@ def initialize(options = {})
       @mailto                           = options.fetch(:mailto, :default_mailto)
       @job_template                     = options.delete(:job_template) || ":job"
       @roles                            = Array(options.delete(:roles))
+      @desc                             = options.delete(:desc)
       @options[:output]                 = options.has_key?(:output) ? Whenever::Output::Redirection.new(options[:output]).to_s : ''
       @options[:environment_variable] ||= "RAILS_ENV"
       @options[:environment]          ||= :production
diff --git a/lib/whenever/job_list.rb b/lib/whenever/job_list.rb
index 7df39c68..aff09c02 100644
--- a/lib/whenever/job_list.rb
+++ b/lib/whenever/job_list.rb
@@ -144,6 +144,7 @@ def cron_jobs_of_time(time, jobs)
         end
         Whenever::Output::Cron.output(time, job, :chronic_options => @chronic_options) do |cron|
           cron << "\n\n"
+          cron = (job.desc.strip + "\n").gsub(/^(.*)$/, '# \1') + cron unless job.desc.to_s.empty?
 
           if cron[0,1] == "@"
             shortcut_jobs << cron
diff --git a/test/functional/output_desc_test.rb b/test/functional/output_desc_test.rb
new file mode 100644
index 00000000..520275c2
--- /dev/null
+++ b/test/functional/output_desc_test.rb
@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class OutputDescTest < Whenever::TestCase
+  test "single line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :desc => "A description" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+
+  test "multi line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :desc => "A description\nhas mulitple lines" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n# has mulitple lines\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+end