Add --describe arg to brew add

README.md

@@ -27,6 +27,9 @@ tap "superatomic/bundle-extensions"
   To use single quotes instead of double quotes for Brewfile lines (e.g. `brew 'bat'` instead of `brew "bat"`),
   set the environment variable `HOMEBREW_BUNDLE_QUOTE_TYPE` to the value `single`.
 
+  To add a descriptive comment above each line (like `brew bundle dump --describe`), use the `--describe` option.
+  This is enabled by default if the environment variable `HOMEBREW_BUNDLE_DUMP_DESCRIBE` is set.
+
 - **`brew drop [FORMULA/CASK...]`**
 
   Removes one or more provided formulae and/or casks from a `Brewfile`.

cmd/add.rb

@@ -24,6 +24,11 @@ def add_args
 
             switch "--formula", "--formulae", description: "Treat all named arguments as formulae."
             switch "--cask", "--casks", description: "Treat all named arguments as casks."
+            switch "--describe",
+                env:         :bundle_dump_describe,
+                description: "Add a descriptive comment above each line, unless the " \
+                             "package does not have a description. " \
+                             "This is enabled by default if `HOMEBREW_BUNDLE_DUMP_DESCRIBE` is set."
 
             conflicts "formula", "cask"
 
@@ -98,6 +103,11 @@ def add
 
                 # Add the formula/cask to the file if it hasn't already been added.
                 unless current_bundle_list.include?(brew.full_name) || (brew_name_resolves_to_full_name && current_bundle_list.include?(brew_name))
+                    # Add a descriptive comment if requested.
+                    # Adapted from `BrewDumper.dump`:
+                    # https://github.com/Homebrew/homebrew-bundle/blob/e4798d8075e1a793f065be3e5e1674ec09193d17/lib/bundle/brew_dumper.rb#L59-L63
+                    file << brew.desc.split("\n").map { |s| "# #{s}\n" }.join if args.describe? && brew.desc
+
                     file << "#{brewfile_prefix_type} #{quote_type}#{brew.full_name}#{quote_type}" << "\n"
 
                     oh1 "Added #{display_type} #{Formatter.identifier(brew.full_name)} to Brewfile" unless silent

cmd/drop.rb

@@ -81,13 +81,24 @@ def drop
                 lines = []
                 has_removed_line = false
 
+                # Store comments that look like they were generated by `--describe` in a buffer.
+                # If it turns out the comments are directly preceding a line that should be dropped,
+                # drop the comments retroactively by resetting the array without pushing it to `lines`.
+                comment_line_buffer = []
+
                 File.foreach(brewfile) do |line|
-                    unless line.match(/^\s*#{brewfile_prefix_type}\s+["'](#{regex_name})["']/)
-                        lines.push(line)
+                    if line.match(/^\s*# (?!brew|cask|tap|mas|whalebrew|vscode)\w/)
+                        comment_line_buffer.push(line)
                     else
-                        has_removed_line = true
+                        unless line.match(/^\s*#{brewfile_prefix_type}\s+["'](#{regex_name})["']/)
+                            lines.push(*comment_line_buffer, line)
+                        else
+                            has_removed_line = true
+                        end
+                        comment_line_buffer = []
                     end
                 end
+                lines.push(*comment_line_buffer) if comment_line_buffer
 
                 # Check to see if any lines were dropped from the file. If not, that's an error!
                 if has_removed_line