Automating Command Execution straight from README.md

Introduction

In today’s software development landscape, README.md files serve as valuable documentation, providing users with important instructions and command snippets to interact with various tools and libraries. However, manually executing these commands one by one can be time-consuming and error-prone. To alleviate this problem, I have created a powerful tool using the Go programming language that can read commands directly from README.md files and execute them automatically. In this article, we will explore the motivation behind the tool, its unique features, and the technologies used to build it.

Image by Author. Example: Select commands from Github README to execute for a repo.

Motivation

The primary motivation behind developing this tool was to streamline the process of executing commands from README.md files found on platforms like GitHub. Copying and pasting commands from these files to the terminal can become tedious, error-prone, and time-consuming, especially when dealing with complex setups or multiple instructions.

Additionally, many organizations still rely on manual operations, where commands are copied and pasted from platforms like Confluence. This manual approach not only increases the risk of human error but also wastes valuable time that could be better spent on other tasks.

Tool Overview

The tool, which I have named re(short for README.md executor), aims to automate the execution of commands directly from README.md files. By leveraging this tool, developers and system administrators can save time, reduce errors, and improve overall productivity.

With the use of ```sh, ```bash or other language identifiers, your code snippets become more accessible, organized, and easily executable. By specifying the language in each code block, developers can seamlessly integrate commands into their projects and improve collaboration.

You can also specify custom tags as ```sh mytag and execute re mytag , which will filter commands only from that code block.

Key Features

Seamless Command Execution: reallows users to execute commands from README.md files without the need for manual copy-pasting. It automatically reads the commands and executes them in the terminal, ensuring accuracy and efficiency.

Image by Author. Example: filter by tags sh from README.md

Error Prevention: Manually copying and pasting commands can lead to mistakes, such as accidentally including incorrect commands or omitting necessary arguments. re eliminates these risks by directly reading commands from the README.md file, leaving no room for human error.

Image by Author. Example: output of selected commands.

MultiLine Support: Multiline commands are supported and executed with no problems.

Image by Author. Example: showing multiline support.

Command History and Status: The tool utilizes key-value (KV) storage to track the execution history of commands. Previous command results are displayed as either red or green, indicating failed or successful executions respectively. This feature helps users quickly identify any problematic commands or troubleshoot issues.

Technologies Used:

1. Go Language: The tool is developed using the Go programming language, known for its simplicity, performance, and excellent concurrency support. Go’s rich standard library and ecosystem make it an ideal choice for building command-line tools.
2. go-survey/survey: For the user interface (UI), reutilizes the go-survey/survey package. Initially, the promptui library was used, but go-survey/survey emerged as a superior choice due to its enhanced functionality, ease of use, and better user experience.

Conclusion

The re tool serves as a valuable asset for developers and system administrators, providing an automated solution for executing commands directly from README.md files. By eliminating manual copy-pasting and leveraging the power of Go, this tool saves time, reduces errors, and enhances productivity.

By incorporating a command history feature and utilizing KV storage, the tool enhances visibility and provides valuable insights into command execution results.

As the first tool of its kind, re showcases the potential for automating manual operations and reducing human error in various software development scenarios. With further refinement and community contributions, this tool has the potential to become an indispensable asset for developers worldwide.

You can find the re tool and its source code on GitHub at the following link:

https://github.com/kevincobain2000/re

Remember, while using re exercise caution and ensure the commands in your README.md files are accurate and safe to execute.