500 Internal server error when visiting link for Pro Git v1 book

[HonkingGoose]

URL for broken page

https://git-scm.com/book/en/v1

Problem

The page linked above leads to a 500 Internal Server Error.

Operating system and browser

macOS 13, Firefox 113.0.1

Steps to reproduce

1. Go to https://git-scm.com/book/en/v1
2. End up at Internal server error page

Other details

The Pro Git book is on version 2 now. We should probably redirect to the landing page for the v2 book.

Related issue (filed in the wrong place):

• Redirect incoming request for https://git-scm.com/book/en/v1 to https://git-scm.com/book/en/v2 progit/progit2#1836

[pedrorijo91]

hey @HonkingGoose @derberg,

can you share where did you find links to book v1?

either way, it seems reasonable to redirect to some page. probably we removed the routing because v1 is really old AFAIK (i see v2 was released around 2014)

[HonkingGoose]

According to the first issue there are links pointing to the v1 version of the book in the GitHub Docs. I will open a PR in the GitHub Docs repo to fix the links.

[HonkingGoose]

I tried making the changes to the GitHub Docs myself, but I'm not allowed to touch the files with the bad links in it. So I'm opening an issue with GitHub Docs, so one of their maintainers can fix it. 😄

[HonkingGoose]

either way, it seems reasonable to redirect to some page. probably we removed the routing because v1 is really old AFAIK (i see v2 was released around 2014)

I'll let you guys decide. Possible fixes:

1. Do nothing, let downstream projects update their own links to broken pages
2. Redirect v1 to v2 in-place: only change v1 to v2 in the link
3. Redirect v1 links to a generic "homepage" for the v2 version of the book

[dscho]

For the record: after #1804 was merged, the link no longer 500s but 404s instead.

[LemmingAvalanche]

Related: I found this link which doesn’t say anything about the edition:

https://git-scm.com/book/en/Git-Tools-Rewriting-History

But this works:

https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

The second edition.

Maybe the first link could try to redirect to /v2?

[dscho]

@LemmingAvalanche good idea! We should automate this by patching in aliases here (both v1.html and v1/index.html), and here (being careful to special-case %3F, i.e. the question mark, also for the v1 redirect).

@LemmingAvalanche want to give it a try?

[LemmingAvalanche]

@dscho Sure thing, I can look at this this evening.

I’ll reply later if it turns out that it needs someone more experienced.

[dscho]

@LemmingAvalanche thank you for clarifying (in a separate, private communication) that you were thinking of redirecting:

https://git-scm.com/book/en/Git-Tools-Rewriting-History

To:

https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

I indeed misunderstood, or maybe it was a Freudian mistake, as the information necessary to reliably map the sections of v1 to v2 is simply not available in the current version of git-scm.com.

But maybe you can add that mapping, say, as /data/book-v1.yml, probably (semi-automatically) generated from a clone of https://github.com/progit/progit/, and then use that information in script/*book*.rb to add the respective aliases?

[dscho]

I had a look, @LemmingAvalanche, just to see the breadth of the effort. Here is a link to Pro Git v1 in the Internet Archive, as of January 2nd, 2014, around the time the 2nd revision was started.

ProGit v1 table of contents

1. 1. Getting Started

   1. 1.1 About Version Control
   2. 1.2 A Short History of Git
   3. 1.3 Git Basics
   4. 1.4 Installing Git
   5. 1.5 First-Time Git Setup
   6. 1.6 Getting Help
   7. 1.7 Summary

2. 2. Git Basics

   1. 2.1 Getting a Git Repository
   2. 2.2 Recording Changes to the Repository
   3. 2.3 Viewing the Commit History
   4. 2.4 Undoing Things
   5. 2.5 Working with Remotes
   6. 2.6 Tagging
   7. 2.7 Tips and Tricks
   8. 2.8 Summary

3. 3. Git Branching

   1. 3.1 What a Branch Is
   2. 3.2 Basic Branching and Merging
   3. 3.3 Branch Management
   4. 3.4 Branching Workflows
   5. 3.5 Remote Branches
   6. 3.6 Rebasing
   7. 3.7 Summary

4. 4. Git on the Server

   1. 4.1 The Protocols
   2. 4.2 Getting Git on a Server
   3. 4.3 Generating Your SSH Public Key
   4. 4.4 Setting Up the Server
   5. 4.5 Public Access
   6. 4.6 GitWeb
   7. 4.7 Gitosis
   8. 4.8 Gitolite
   9. 4.9 Git Daemon
   10. 4.10 Hosted Git
   11. 4.11 Summary

5. 5. Distributed Git

   1. 5.1 Distributed Workflows
   2. 5.2 Contributing to a Project
   3. 5.3 Maintaining a Project
   4. 5.4 Summary

6. 6. Git Tools

   1. 6.1 Revision Selection
   2. 6.2 Interactive Staging
   3. 6.3 Stashing
   4. 6.4 Rewriting History
   5. 6.5 Debugging with Git
   6. 6.6 Submodules
   7. 6.7 Subtree Merging
   8. 6.8 Summary

7. 7. Customizing Git

   1. 7.1 Git Configuration
   2. 7.2 Git Attributes
   3. 7.3 Git Hooks
   4. 7.4 An Example Git-Enforced Policy
   5. 7.5 Summary

8. 8. Git and Other Systems

   1. 8.1 Git and Subversion
   2. 8.2 Migrating to Git
   3. 8.3 Summary

9. 9. Git Internals

   1. 9.1 Plumbing and Porcelain
   2. 9.2 Git Objects
   3. 9.3 Git References
   4. 9.4 Packfiles
   5. 9.5 The Refspec
   6. 9.6 Transfer Protocols
   7. 9.7 Maintenance and Data Recovery
   8. 9.8 Summary

10. Index of Commands

And here is the current version of the ProGit v2 book:

ProGit v2 table of contents

1. 1. Getting Started

   1. 1.1 About Version Control
   2. 1.2 A Short History of Git
   3. 1.3 What is Git?
   4. 1.4 The Command Line
   5. 1.5 Installing Git
   6. 1.6 First-Time Git Setup
   7. 1.7 Getting Help
   8. 1.8 Summary

2. 2. Git Basics

   1. 2.1 Getting a Git Repository
   2. 2.2 Recording Changes to the Repository
   3. 2.3 Viewing the Commit History
   4. 2.4 Undoing Things
   5. 2.5 Working with Remotes
   6. 2.6 Tagging
   7. 2.7 Git Aliases
   8. 2.8 Summary

3. 3. Git Branching

   1. 3.1 Branches in a Nutshell
   2. 3.2 Basic Branching and Merging
   3. 3.3 Branch Management
   4. 3.4 Branching Workflows
   5. 3.5 Remote Branches
   6. 3.6 Rebasing
   7. 3.7 Summary

4. 4. Git on the Server

   1. 4.1 The Protocols
   2. 4.2 Getting Git on a Server
   3. 4.3 Generating Your SSH Public Key
   4. 4.4 Setting Up the Server
   5. 4.5 Git Daemon
   6. 4.6 Smart HTTP
   7. 4.7 GitWeb
   8. 4.8 GitLab
   9. 4.9 Third Party Hosted Options
   10. 4.10 Summary

5. 5. Distributed Git

   1. 5.1 Distributed Workflows
   2. 5.2 Contributing to a Project
   3. 5.3 Maintaining a Project
   4. 5.4 Summary

6. 6. GitHub

   1. 6.1 Account Setup and Configuration
   2. 6.2 Contributing to a Project
   3. 6.3 Maintaining a Project
   4. 6.4 Managing an organization
   5. 6.5 Scripting GitHub
   6. 6.6 Summary

7. 7. Git Tools

   1. 7.1 Revision Selection
   2. 7.2 Interactive Staging
   3. 7.3 Stashing and Cleaning
   4. 7.4 Signing Your Work
   5. 7.5 Searching
   6. 7.6 Rewriting History
   7. 7.7 Reset Demystified
   8. 7.8 Advanced Merging
   9. 7.9 Rerere
   10. 7.10 Debugging with Git
   11. 7.11 Submodules
   12. 7.12 Bundling
   13. 7.13 Replace
   14. 7.14 Credential Storage
   15. 7.15 Summary

8. 8. Customizing Git

   1. 8.1 Git Configuration
   2. 8.2 Git Attributes
   3. 8.3 Git Hooks
   4. 8.4 An Example Git-Enforced Policy
   5. 8.5 Summary

9. 9. Git and Other Systems

   1. 9.1 Git as a Client
   2. 9.2 Migrating to Git
   3. 9.3 Summary

10. 10. Git Internals

    1. 10.1 Plumbing and Porcelain
    2. 10.2 Git Objects
    3. 10.3 Git References
    4. 10.4 Packfiles
    5. 10.5 The Refspec
    6. 10.6 Transfer Protocols
    7. 10.7 Maintenance and Data Recovery
    8. 10.8 Environment Variables
    9. 10.9 Summary

11. A1. Appendix A: Git in Other Environments

    1. A1.1 Graphical Interfaces
    2. A1.2 Git in Visual Studio
    3. A1.3 Git in Visual Studio Code
    4. A1.4 Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine
    5. A1.5 Git in Sublime Text
    6. A1.6 Git in Bash
    7. A1.7 Git in Zsh
    8. A1.8 Git in PowerShell
    9. A1.9 Summary

12. A2. Appendix B: Embedding Git in your Applications

    1. A2.1 Command-line Git
    2. A2.2 Libgit2
    3. A2.3 JGit
    4. A2.4 go-git
    5. A2.5 Dulwich

13. A3. Appendix C: Git Commands

    1. A3.1 Setup and Config
    2. A3.2 Getting and Creating Projects
    3. A3.3 Basic Snapshotting
    4. A3.4 Branching and Merging
    5. A3.5 Sharing and Updating Projects
    6. A3.6 Inspection and Comparison
    7. A3.7 Debugging
    8. A3.8 Patching
    9. A3.9 Email
    10. A3.10 External Systems
    11. A3.11 Administration
    12. A3.12 Plumbing Commands

And here is the result of my best effort at mapping them:

v1	v2
1. Getting Started	1. Getting Started
1.1 About Version Control	1.1 About Version Control
1.2 A Short History of Git	1.2 A Short History of Git
1.3 Git Basics	1.3 What is Git?
	1.4 The Command Line
1.4 Installing Git	1.5 Installing Git
1.5 First-Time Git Setup	1.6 First-Time Git Setup
1.6 Getting Help	1.7 Getting Help
1.7 Summary	1.8 Summary
2. Git Basics	2. Git Basics
2.1 Getting a Git Repository	2.1 Getting a Git Repository
2.2 Recording Changes to the Repository	2.2 Recording Changes to the Repository
2.3 Viewing the Commit History	2.3 Viewing the Commit History
2.4 Undoing Things	2.4 Undoing Things
2.5 Working with Remotes	2.5 Working with Remotes
2.6 Tagging	2.6 Tagging
2.7 Tips and Tricks	2.7 Git Aliases
2.8 Summary	2.8 Summary
3. Git Branching	3. Git Branching
3.1 What a Branch Is	3.1 Branches in a Nutshell
3.2 Basic Branching and Merging	3.2 Basic Branching and Merging
3.3 Branch Management	3.3 Branch Management
3.4 Branching Workflows	3.4 Branching Workflows
3.5 Remote Branches	3.5 Remote Branches
3.6 Rebasing	3.6 Rebasing
3.7 Summary	3.7 Summary
4. Git on the Server	4. Git on the Server
4.1 The Protocols	4.1 The Protocols
4.2 Getting Git on a Server	4.2 Getting Git on a Server
4.3 Generating Your SSH Public Key	4.3 Generating Your SSH Public Key
4.4 Setting Up the Server	4.4 Setting Up the Server
4.5 Public Access
4.6 GitWeb
4.7 Gitosis
4.8 Gitolite
4.9 Git Daemon	4.5 Git Daemon
4.10 Hosted Git
	4.6 Smart HTTP
	4.7 GitWeb
	4.8 GitLab
	4.9 Third Party Hosted Options
4.11 Summary	4.10 Summary
5. Distributed Git	5. Distributed Git
5.1 Distributed Workflows	5.1 Distributed Workflows
5.2 Contributing to a Project	5.2 Contributing to a Project
5.3 Maintaining a Project	5.3 Maintaining a Project
5.4 Summary	5.4 Summary
	6. GitHub
	6.1 Account Setup and Configuration
	6.2 Contributing to a Project
	6.3 Maintaining a Project
	6.4 Managing an organization
	6.5 Scripting GitHub
	6.6 Summary
6. Git Tools	7. Git Tools
6.1 Revision Selection	7.1 Revision Selection
6.2 Interactive Staging	7.2 Interactive Staging
6.3 Stashing	7.3 Stashing and Cleaning
	7.4 Signing Your Work
	7.5 Searching
6.4 Rewriting History	7.6 Rewriting History
	7.7 Reset Demystified
	7.8 Advanced Merging
	7.9 Rerere
6.5 Debugging with Git	7.10 Debugging with Git
6.6 Submodules	7.11 Submodules
	7.12 Bundling
	7.13 Replace
	7.14 Credential Storage
6.7 Subtree Merging
6.8 Summary	7.15 Summary
7. Customizing Git	8. Customizing Git
7.1 Git Configuration	8.1 Git Configuration
7.2 Git Attributes	8.2 Git Attributes
7.3 Git Hooks	8.3 Git Hooks
7.4 An Example Git-Enforced Policy	8.4 An Example Git-Enforced Policy
7.5 Summary	8.5 Summary
8. Git and Other Systems	9. Git and Other Systems
8.1 Git and Subversion	9.1 Git as a Client
8.2 Migrating to Git	9.2 Migrating to Git
8.3 Summary	9.3 Summary
9. Git Internals	10. Git Internals
9.1 Plumbing and Porcelain	10.1 Plumbing and Porcelain
9.2 Git Objects	10.2 Git Objects
9.3 Git References
9.4 Packfiles	10.4 Packfiles
9.5 The Refspec	10.5 The Refspec
9.6 Transfer Protocols	10.6 Transfer Protocols
9.7 Maintenance and Data Recovery	10.7 Maintenance and Data Recovery
	10.8 Environment Variables
9.8 Summary	10.9 Summary
	A1. Appendix A: Git in Other Environments
	A1.1 Graphical Interfaces
	A1.2 Git in Visual Studio
	A1.3 Git in Visual Studio Code
	A1.4 Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine
	A1.5 Git in Sublime Text
	A1.6 Git in Bash
	A1.7 Git in Zsh
	A1.8 Git in PowerShell
	A1.9 Summary
	A2. Appendix B: Embedding Git in your Applications
	A2.1 Command-line Git
	A2.2 Libgit2
	A2.3 JGit
	A2.4 go-git
	A2.5 Dulwich
Index of Commands	A3. Appendix C: Git Commands
	A3.1 Setup and Config
	A3.2 Getting and Creating Projects
	A3.3 Basic Snapshotting
	A3.4 Branching and Merging
	A3.5 Sharing and Updating Projects
	A3.6 Inspection and Comparison
	A3.7 Debugging
	A3.8 Patching
	A3.9 Email
	A3.10 External Systems
	A3.11 Administration
	A3.12 Plumbing Commands

As you can see, there are quite a few gaps, in particular in chapter 4 there are gaps on the v2 side, which means they are unmappable.

Still, these could potentially be mapped, likely via appending aliases here after adding a manual mapping like this:

v1_mapping = {
  "1.1" => "/book/en/Getting-Started-About-Version-Control",
  "1.2" => "/book/en/Getting-Started-A-Short-History-of-Git",
  ...
}

...

v1_path = v1_mapping[self.cs_number]
unless v1_path.nil?
  front_matter["aliases"] = [] if front_matter["aliases"].nil?
  front_matter["aliases"] << v1_path
end

The mapping would need to be crafted manually, of course.

However, the challenges are not stopping there. What about anchors? As a concrete example: /book/en/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository would need to be mapped to /book/en/v2/Git-Basics-Getting-a-Git-Repository#_git_cloning. That is not really automatable, I think.

And then I would like to draw your attention to the fact that the ProGit v1 book had translation which would need to be handled, too:

This book is translated into German, 中文, French, Japanese, Dutch, Russian, Korean, Brazilian Portuguese and Czech.

Partial translations available in Arabic, Spanish, Indonesian, Italian, Finnish, Macedonian, Polish, Turkish and Taiwanese Mandarin,

Translations started for Azerbaijani, Belarusian, Catalan, Esperanto. Spanish (Nicaragua), Hungarian, Norwegian Bokmål, Romanian, Serbian, Thai and Vietnamese.

tl;dr this would be a huge effort. Given that the v1 URLs have stopped working over four years ago, I consider this not worth doing.

[LemmingAvalanche]

@dscho Thank you for doing that research. I agree that it’s best to not do anything here.

All I’ve done on this subject is to search Stackoverflow for v1 links and update them when there is a v2 mapping. That’s what we can do at this stage (all these years later).

[HonkingGoose]

How about creating a landing page for incoming "progit v1 link users"? Like this:

1. Bob clicks on outdated link to v1 book. Server redirects all v1 links to the new v1 to v2 page.
2. The page explains that Bob used an old link.
3. The page shows a prominent link or button, that links to the table of contents for the v2 book on git.scm.
4. Bob clicks on the v2 link, and reads the table of contents to find a similar chapter.

This way you avoid doing any manual mapping from v1 to v2. And you give users a simple way to recover from the outdated link.

[dscho]

How about creating a landing page for incoming "progit v1 link users"?

@HonkingGoose that would require hosting a server so that arbitrary /book/v1/ routes could be redirected. But since #1804 was merged, git-scm.com is a static site. No wildcard routes available there.

There is some sort of an option to do wildcard routes: https://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository serves the 404.html page. Javascript could be added to that page to detect v1 book links and reroute, but that would not work for browsers (or crawlers) that have (nor want) Javascript support.

What we could do is to scrape the v1 links from the Internet Archive and then present them as aliases for something like this new "ProGit v1 landing page". But that would already be 90% of the work to redirect them (modulo anchor) to the v2 pages. So I think that if we already do the work to identify all of the v1 links, we might just as well go the whole nine yards and save us the work of creating a new page.