From a65dca5d5e9b4bc71722bc91a5641126a1b0ec61 Mon Sep 17 00:00:00 2001
From: Simon Johnsson <simon.johnsson@canonical.com>
Date: Thu, 2 Oct 2025 12:49:58 +0200
Subject: Add history undo, redo, and rollback features

---
 apt-pkg/history.cc |  1 +
 apt-pkg/history.h  | 61 ++++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 51 insertions(+), 11 deletions(-)

(limited to 'apt-pkg')

diff --git a/apt-pkg/history.cc b/apt-pkg/history.cc
index 4e838a016..dc48c5464 100644
--- a/apt-pkg/history.cc
+++ b/apt-pkg/history.cc
@@ -16,6 +16,7 @@
 #include <apt-pkg/tagfile.h>
 
 #include <algorithm>
+#include <cassert>
 #include <cctype>
 
 #include <glob.h>
diff --git a/apt-pkg/history.h b/apt-pkg/history.h
index 08e7be388..899d59b24 100644
--- a/apt-pkg/history.h
+++ b/apt-pkg/history.h
@@ -20,38 +20,58 @@
 namespace APT::History
 {
 
+/**
+ * @enum class Kind
+ * @brief Represents the possible actions of APT transactions in history.
+ */
 enum class Kind
 {
    Install,
    Reinstall,
    Upgrade,
    Downgrade,
+   InstallEnd = Downgrade,
    Remove,
    Purge,
 };
 
-// KindToString - Take a kind and return its
-// string representation.
-//
-// NOTE: Non-localized English version
+/**
+ * Get the string parsing specific string representation 
+ * of a @ref Kind.
+ *
+ * @param kind An action kind.
+ * @return A string representation.
+ *
+ * @note This string representation is not localized.
+ */
 std::string KindToString(const Kind &kind);
 
+/**
+ * @struct Change
+ * @brief Represents a package change.
+ */
 struct Change
 {
    Kind kind;
    std::string package;
    std::string currentVersion;
    std::string candidateVersion;
-   bool automatic = false;
+   bool automatic = false; ///< If the change was automatically performed.
 
    private:
    void *d; // pointer for future extension;
 };
 
+static inline bool IsRemoval(const Kind &kind) { return kind > Kind::InstallEnd; }
+
+/**
+ * @struct Entry
+ * @brief Represents an entry in the APT history log.
+ */
 struct Entry
 {
    // Strings instead of string_view to avoid reference errors
-   std::string startDate;
+   std::string startDate;  
    std::string endDate;
    std::string cmdLine;
    std::string comment;
@@ -66,15 +86,34 @@ struct Entry
 // History is defined as the collection of entries in the history log(s).
 typedef std::vector<Entry> HistoryBuffer;
 
-// ParseSection - Take a tag section and parse it as a
-// history log entry.
+/**
+ * Parse a tag section as history log entry.
+ *
+ * @param section A tag section.
+ * @return A history log entry.
+ */
 APT_PUBLIC Entry ParseSection(const pkgTagSection &section);
-// ParseFile - Take a file descriptor and parse it as a history
-// log to the given buffer.
-// NOTE: Caller is responsible for closing the file descriptor.
+
+/**
+ * Parse a file descriptor to a history buffer.
+ *
+ * @param fd A file descriptor.
+ * @param buf A history buffer.
+ * @return true if successful, false otherwise.
+ *
+ * @note Caller is responsible for closing the file descriptor.
+ */
 APT_PUBLIC bool ParseFile(FileFd &fd, HistoryBuffer &buf);
+
 // ParseLogDir - Parse the apt history log directory to the buffer.
+/**
+ * Parse the APT history log directory to a buffer.
+ *
+ * @param buf A history buffer.
+ * @return true if successful, false otherwise.
+ */
 APT_PUBLIC bool ParseLogDir(HistoryBuffer &buf);
+
 } // namespace APT::History
 
 #endif
-- 
cgit v1.2.3-70-g09d2