Software 2.0

AI驱动的README生成器

admin -

我对冗余任务的容忍度非常低，这是AI如此令人兴奋的前景的一部分。效率低下的一种是手动更新项目的README.md文件。如果你曾经发现保持最新或希望以一种毫不费力地生成详细，一致的文档的方式很乏味，那么你就在正确的位置。通过组合git钩，一些bash脚本和大型语言模型，你可以自动化生成READMD.md文件的过程，从而确保你的文档与代码库一样新鲜。

在本文中，我们将介绍建立一个使用Git钩子和Ollama Llama3模型自动生成和更新README.md的方法。 用LLM处理文档问题，这将使你可以专注于代码。

为什么要自动化README的生成？

为每个存储库维持高质量的README.md可能很乏味。好的README应该：

  • 提供该项目的概述。
  • 详细的安装步骤，使用示例和依赖项。
  • 包括有关如何贡献，许可和有用链接的信息。

通过自动化此过程，我们可以节省时间并避免手动错误，同时确保记录了项目结构的关键方面。

1、先决条件

在运行脚本之前，请确保在系统上安装和配置Ollama CLI。您可以通过执行以下命令来验证Ollama正在运行：

ollama list

如果Ollama处于活动状态，你将看到其当前状态和任何运行模型。如果不是，请按照Ollama安装指南进行设置。

先决条件到位后，将脚本保存为存储库中的固定钩子。确保授予其执行权限：

chmod +x .git/hooks/post-commit

该脚本将在每次提交后自动运行，使你的README保持最新。

2、Post-Commit钩子概述

Post-Commit钩子是每个git提交之后运行的脚本。我们利用它：

  • 生成README.md文件。
  • 使用Llama 3模型对项目进行全面描述。
  • 自动提交README.md文件，使用标志机制避免无限循环。

让我们开始：

# File path to the README
README_FILE="README.md"
# Temporary flag file to prevent infinite loop
FLAG_FILE=".readme_generated"
# Check for files that have been changed
CHANGED_FILES=$(git diff --cached --name-only)
# If the flag file exists, skip the hook to avoid the infinite loop
if [ -f "$FLAG_FILE" ]; then
  echo "README already generated, skipping hook."
  rm "$FLAG_FILE"  # Clean up flag file for future commits
  exit 0
fi
# If only the README file is changed, skip the hook to avoid infinite loop
if [[ "$CHANGED_FILES" == "$README_FILE" ]]; then
  echo "Only README.md has changed. Skipping README generation."
  exit 0
fi

3、收集项目信息

脚本需要收集基本的项目信息，例如名称，版本，描述和依赖项。这是这样做的：

  • node.js项目：如果有一个 package.json，我们提取项目的名称，版本，描述和依赖项。
  • python项目：如果找到 requirements.txt文件，则可以将依赖项提取并将其包括在README中。
# Get repository URL from git config
REPO_URL=$(git config --get remote.origin.url)
# Initialize project info
PROJECT_INFO=""
# Extract project name, version, and description from package.json (Node.js example)
if [ -f "package.json" ]; then
  PROJECT_NAME=$(jq -r '.name' package.json)
  PROJECT_VERSION=$(jq -r '.version' package.json)
  PROJECT_DESCRIPTION=$(jq -r '.description' package.json)
  DEPENDENCIES=$(jq -r '.dependencies | keys | join(", ")' package.json)
  PROJECT_INFO+="Project: $PROJECT_NAME\nVersion: $PROJECT_VERSION\nDescription: $PROJECT_DESCRIPTION\nDependencies: $DEPENDENCIES\n"
fi
# If it's a Python project with requirements.txt, extract dependencies
if [ -f "requirements.txt" ]; then
  DEPENDENCIES=$(cat requirements.txt | tr '\n' ', ')
  PROJECT_INFO+="Python Dependencies: $DEPENDENCIES\n"
fi

4、提取文件夹结构和关键文件

接下来，我们提取项目的文件夹结构（不包括 .git目录），并获取重要文件列表，例如 .js， .py和 .ipynb。该脚本甚至抓住每个文件的前五行，为每个文件的作用提供一些上下文。

# Extract folder structure
FOLDER_STRUCTURE=$(find . -maxdepth 2 -type d | grep -v '\.git')
# Extract a list of key files with brief summaries (e.g., first 5 lines of each)
KEY_FILES=$(find . -maxdepth 1 -type f \( -name "*.js" -o -name "*.py" -o -name "*.ipynb" \))
FILE_SUMMARIES=""
for file in $KEY_FILES; do
  FILE_CONTENT=$(head -n 5 "$file")
  FILE_SUMMARIES+="$file:\n$FILE_CONTENT\n\n"
done

5、使用Ollama生成README文件

有了收集的信息，我们创建了发送给Ollama的提示。该提示包括存储库URL，项目详细信息，文件夹结构和文件摘要。 Llama 3基于此信息生成README.md。

# Combine project info, folder structure, file summaries, and repo URL into a prompt
PROMPT="Generate a detailed README file for a project with the following details:
Repository URL: $REPO_URL
$PROJECT_INFO
Folder structure:
$FOLDER_STRUCTURE
Key files and their contents:
$FILE_SUMMARIES
Include sections: Overview, Installation, Usage, Contribution Guidelines, Repo Links, and License."
echo -e "$PROMPT"
# Use Ollama to generate README content
ollama run llama3:latest "$PROMPT" > $README_FILE

6、提交README

为了防止钩子保持触发的无限循环，我们使用一个标志文件 .readme_generated。此文件是在生成读数之后创建的。如果钩子在随后的运行中看到此标志，它会跳过自动化的生成步骤。最后，如果更新了README，则脚本阶段并提交新文件。

# Set flag to indicate README was generated
touch "$FLAG_FILE"
# Check if the README was updated
if [[ `git status --porcelain` ]]; then
  # Add the updated README file to the staging area
  git add $README_FILE
  
  # Commit the updated README
  git commit -m "Auto-updated README using Ollama"
  echo "README updated and committed."
else
  echo "No changes detected in README."
fi

7、结束语

通过自动化README的生成，你可以通过最少的手动努力确保文档保持最新。该脚本由Llama 3语言模型提供动力，可以平稳地集成到你的git工作流程中，每次提交代码时都会生成详细的项目文档。

这是完整的脚本：

#!/bin/bash

# File path to the README
README_FILE="README.md"

# Temporary flag file to prevent infinite loop
FLAG_FILE=".readme_generated"

# Check for files that have been changed
CHANGED_FILES=$(git diff --cached --name-only)

# If the flag file exists, skip the hook to avoid the infinite loop
if [ -f "$FLAG_FILE" ]; then
  echo "README already generated, skipping hook."
  rm "$FLAG_FILE"  # Clean up flag file for future commits
  exit 0
fi

# If only the README file is changed, skip the hook to avoid infinite loop
if [[ "$CHANGED_FILES" == "$README_FILE" ]]; then
  echo "Only README.md has changed. Skipping README generation."
  exit 0
fi

# Get repository URL from git config
REPO_URL=$(git config --get remote.origin.url)

# Initialize project info
PROJECT_INFO=""

# Extract project name, version, and description from package.json (Node.js example)
if [ -f "package.json" ]; then
  PROJECT_NAME=$(jq -r '.name' package.json)
  PROJECT_VERSION=$(jq -r '.version' package.json)
  PROJECT_DESCRIPTION=$(jq -r '.description' package.json)
  DEPENDENCIES=$(jq -r '.dependencies | keys | join(", ")' package.json)

  PROJECT_INFO+="Project: $PROJECT_NAME\nVersion: $PROJECT_VERSION\nDescription: $PROJECT_DESCRIPTION\nDependencies: $DEPENDENCIES\n"
fi

# If it's a Python project with requirements.txt, extract dependencies
if [ -f "requirements.txt" ]; then
  DEPENDENCIES=$(cat requirements.txt | tr '\n' ', ')
  PROJECT_INFO+="Python Dependencies: $DEPENDENCIES\n"
fi

# Extract folder structure
FOLDER_STRUCTURE=$(find . -maxdepth 2 -type d | grep -v '\.git')

# Extract a list of key files with brief summaries (e.g., first 5 lines of each)
KEY_FILES=$(find . -maxdepth 1 -type f \( -name "*.js" -o -name "*.py" -o -name "*.ipynb" \))
FILE_SUMMARIES=""
for file in $KEY_FILES; do
  FILE_CONTENT=$(head -n 5 "$file")
  FILE_SUMMARIES+="$file:\n$FILE_CONTENT\n\n"
done

# Combine project info, folder structure, file summaries, and repo URL into a prompt
PROMPT="Generate a detailed README file for a project with the following details:
Repository URL: $REPO_URL
$PROJECT_INFO
Folder structure:
$FOLDER_STRUCTURE
Key files and their contents:
$FILE_SUMMARIES
Include sections: Overview, Installation, Usage, Contribution Guidelines, Repo Links, and License."

echo -e "$PROMPT"
# Use Ollama to generate README content
ollama run llama3:latest "$PROMPT" > $README_FILE

# Set flag to indicate README was generated
touch "$FLAG_FILE"

# Check if the README was updated
if [[ `git status --porcelain` ]]; then
  # Add the updated README file to the staging area
  git add $README_FILE
  
  # Commit the updated README
  git commit -m "Auto-updated README using Ollama"

  echo "README updated and committed."
else
  echo "No changes detected in README."
fi

你可以在github存储库中查看此设置的示例。

原文链接：Automate README Generation With Ollama (Llama 3) and Git Hooks

汇智网翻译整理，转载请标明出处