Add support for re-writing a project’s history

If you’re consuming this tool and using it to tell the story of your project’s origins and growth, you might be tempted to become a bit of a revisionist historian.

This might come as a shock, but this project was not perfected implemented from the start, and is in fact the result of countless pick, squash, reword, fixup, and drop rebase operations.

While this can be harmless for pre-released projects, rewriting history once the resulting website is deployed and publicized would result in 404s and broken URLs.

To counteract this, git-read will include and compile pages for any commits that are git tag-ed, along with the rest of their history.

To denote that a commit is “out of date”, and is no longer available on the main branch, calls to Middleman’s proxy have been updated to pass in the out_of_date local Boolean to denote whether or not a page is built from a tagged commit. When rendering from the main branch or the project’s README.md, out_of_date is declared as false.

In the case where the main branch and the tagged commit share ancestors, the main branch’s version will be rendered second, and won’t display the “stale” banner.

Test coverage

To ensure that the new feature is covered by tests, this commit extends the new GitHelpers module to enable tests to switch git branches (via #switch_branch), and to add tagged commits (via #add_tag).

README.md

diff --git a/README.md b/README.md
index 7762285..111c8db 100644
--- a/README.md
+++ b/README.md
@@ -42,3 +42,27 @@ OPTIONS
 ```
 
 [subcommand]: http://mirrors.edge.kernel.org/pub/software/scm/git/docs/howto/new-command.html
+
+Revising a Project's History
+---
+
+If you're consuming this tool and using it to tell the story of your
+project's origins and growth, you might be tempted to become a bit of a
+revisionist historian.
+
+This might come as a shock, but this project was not perfected
+implemented from the start, and is in fact the result of countless
+[`pick`, `squash`, `reword`, `fixup`, and `drop` rebase
+operations][rebase].
+
+While this can be harmless for pre-released projects, rewriting history
+once the resulting website is deployed and publicized would result in
+[`404`s and broken URLs][404].
+
+To counteract this, `git-read` will include and compile pages for any
+commits that are [`git tag`-ed][git-tag], along with the rest of their
+history.
+
+[rebase]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_changing_multiple
+[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
+[git-tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging

config.rb

diff --git a/config.rb b/config.rb
index 547baca..465fb82 100644
--- a/config.rb
+++ b/config.rb
@@ -44,10 +44,50 @@ page '/*.txt', layout: false
 repository_directory = Pathname(ENV.fetch("GIT_DIR", File.dirname(__FILE__)))
 repository = Git.open(repository_directory)
 
+repository.tags.each do |tag|
+  stale_history = History.new(
+    name: repository_directory.basename,
+    readme: repository.show("#{tag.name}:README.md") ,
+    repository: repository,
+    root: tag,
+    out_of_date: true,
+  )
+
+  stale_history.commits.each do |commit|
+    proxy(
+      commit_path(commit),
+      "/commits/commit.html",
+      locals: {
+        history: stale_history,
+        commit: commit,
+        page: {
+          title: commit.message.lines.first,
+        },
+      },
+      ignore: true,
+    )
+  end
+
+  proxy(
+    tag_path(tag),
+    "README.html",
+    locals: {
+      history: stale_history,
+      commit: stale_history.initial_commit,
+      contents: stale_history.readme,
+      page: {
+        title: stale_history.readme.lines.first,
+      },
+    },
+    ignore: true,
+  )
+end
+
 history = History.new(
   name: repository_directory.basename,
   readme: repository.show("HEAD:README.md"),
   repository: repository,
+  root: repository
 )
 
 history.commits.each do |commit|

helpers/url_helpers.rb

diff --git a/helpers/url_helpers.rb b/helpers/url_helpers.rb
index b375b35..3db5e7b 100644
--- a/helpers/url_helpers.rb
+++ b/helpers/url_helpers.rb
@@ -3,7 +3,15 @@ module UrlHelpers
     "/commits/#{commit.sha}/index.html"
   end
 
-  def root_path
-    "/index.html"
+  def tag_path(tag)
+    "/tags/#{tag.name}/index.html"
+  end
+
+  def root_path(root = nil)
+    if root.respond_to? :name
+      tag_path(root)
+    else
+      "/index.html"
+    end
   end
 end

lib/models/history.rb

diff --git a/lib/models/history.rb b/lib/models/history.rb
index 375b095..c156a3c 100644
--- a/lib/models/history.rb
+++ b/lib/models/history.rb
@@ -1,10 +1,12 @@
 class History
-  attr_reader :name, :readme, :repository
+  attr_reader :name, :readme, :repository, :root
 
-  def initialize(name:, readme:, repository:)
+  def initialize(name:, readme:, repository:, root:, out_of_date: false)
     @name = name
     @readme = readme
     @repository = repository
+    @root = root
+    @out_of_date = out_of_date
   end
 
   def initial_commit
@@ -12,6 +14,10 @@ class History
   end
 
   def commits
-    repository.log(nil).reverse_each
+    root.log(nil).reverse_each
+  end
+
+  def out_of_date?
+    @out_of_date
   end
 end

source/layouts/layout.erb

diff --git a/source/layouts/layout.erb b/source/layouts/layout.erb
index 05c77b5..3be8415 100644
--- a/source/layouts/layout.erb
+++ b/source/layouts/layout.erb
@@ -12,7 +12,7 @@
   <body class="min-h-screen">
     <header class="flex flex-row h-12 border-b">
       <h1 class="flex items-center justify-center w-full md:border-r md:w-96">
-        <% current_link_to root_path do %>
+        <% current_link_to root_path(history.root) do %>
           <%= escape_html(history.name) %>
         <% end %>
       </h1>
@@ -59,6 +59,18 @@
 
       <article class="flex-grow justify-center p-4 md:flex md:h-screen-fit md:p-8 md:overflow-y-auto">
         <section class="prose prose-lg md:prose-xl">
+          <% if history.out_of_date? %>
+            <aside class="text-center p-5">
+              <mark>
+                You're viewing an out-of-date version of the project.
+
+                <% link_to root_path do %>
+                  Read the latest version.
+                <% end %>
+              </mark>
+            </aside>
+          <% end %>
+
           <%= yield %>
         </section>
       </article>

test/git_helpers.rb

diff --git a/test/git_helpers.rb b/test/git_helpers.rb
index 0cff2c7..d78db25 100644
--- a/test/git_helpers.rb
+++ b/test/git_helpers.rb
@@ -51,4 +51,22 @@ module GitHelpers
   ensure
     FileUtils.rm_rf(directory)
   end
+
+  def switch_branch(branch_name, from: main_branch, &block)
+    branch = @repository.branch(branch_name)
+
+    branch.checkout
+
+    block.call(branch).tap { branch.gcommit }
+  ensure
+    from.checkout
+  end
+
+  def main_branch
+    %i[ main master ].map { |name| @repository.branches[name] }.find(&:present?)
+  end
+
+  def tag_head_commit(tag_name)
+    @repository.add_tag(tag_name)
+  end
 end

test/system/visitor_views_a_stale_commit_test.rb

diff --git a/test/system/visitor_views_a_stale_commit_test.rb b/test/system/visitor_views_a_stale_commit_test.rb
new file mode 100644
index 0000000..e598713
--- /dev/null
+++ b/test/system/visitor_views_a_stale_commit_test.rb
@@ -0,0 +1,82 @@
+require "application_system_test_case"
+
+class VisitorViewsAStaleCommitTest < ApplicationSystemTestCase
+  test "visitor views a stale commit" do
+    stage_file("README.md", "Ignore me ")
+    commit("Initial commit")
+    branch_commit_sha = switch_branch("my-branch") do
+      stage_file("file.txt", "Ignore me")
+      commit("Hello from the branch")
+      tag_head_commit("my-tag")
+    end
+
+    with_git_repository do
+      visit commit_path(branch_commit_sha)
+      expand_history
+
+      assert_text "You're viewing an out-of-date version of the project."
+      assert_link text: "Read the latest version."
+      assert_selector "h1", text: "Hello from the branch"
+      assert_selector "[aria-current]", text: "Hello from the branch"
+    end
+  end
+
+  test "visitor views stale README" do
+    stage_file("README.md", "Ignore me ")
+    commit("Initial commit")
+    branch_commit_sha = switch_branch("my-branch") do
+      stage_file("README.md", "# Tagged README")
+      commit("Hello from the branch")
+      tag_head_commit("my-tag")
+    end
+
+    with_git_repository do
+      visit tag_path(branch_commit_sha)
+      expand_history
+
+      assert_text "You're viewing an out-of-date version of the project."
+      assert_selector "h1", text: "Tagged README"
+      assert_text "Hello from the branch"
+    end
+  end
+
+  test "visitor navigates to the stale root" do
+    stage_file("README.md", "README contents from the main branch")
+    commit("Initial commit")
+    branch_commit_sha = switch_branch("my-branch") do
+      stage_file("file.txt", "Ignore me")
+      commit("Hello from the branch")
+      tag_head_commit("my-tag")
+    end
+
+    with_git_repository do |directory|
+      visit commit_path(branch_commit_sha)
+      click_on directory.basename
+      expand_history
+
+      assert_text "You're viewing an out-of-date version of the project."
+      assert_text "README contents from the main branch"
+      assert_link text: "Hello from the branch"
+    end
+  end
+
+  test "visitor does not see stale commit from main branch" do
+    stage_file("README.md", "Ignore me")
+    commit("Hello from main branch")
+    switch_branch("my-branch") do
+      stage_file("file.txt", "Ignore me")
+      commit("Hello from the branch")
+      tag_head_commit("my-tag")
+    end
+
+    with_git_repository do
+      visit root_path
+      expand_history
+
+      assert_link "Hello from main branch"
+      assert_no_text "You're viewing an out-of-date version of the project."
+      assert_no_link "Read the latest version."
+      assert_no_link "Hello from the branch"
+    end
+  end
+end