Shell scripting standards and style guidelines

原文：https://docs.gitlab.com/ee/development/shell_scripting_guide/

Shell scripting standards and style guidelines

Overview

GitLab 由许多不同的服务和子项目组成. 他们的大多数后端代码都是用Ruby和Go编写的. 但是，其中一些使用 shell 脚本来自动化日常系统管理任务，例如部署，安装等.之所以这样做是出于历史原因，或者是为了最大程度地减少对 Docker 映像的依赖性.

该页面旨在根据我们的各种经验来定义和组织我们的 Shell 脚本编写准则. GitLab 项目中的所有 Shell 脚本最终都应与本指南保持一致. 如果每个项目与本指南存在差异，则应在此类项目的README.md或PROCESS.md文件中进行说明.

Avoid using shell scripts

注意：这是必读部分.

综上所述，我们建议尽可能远离 Shell 脚本. 像 Ruby 或 Python 这样的语言（如果需要与我们利用的代码库保持一致），几乎总是一个更好的选择. 高级解释语言具有更易读的语法，为单元测试，整理和错误报告提供了更成熟的功能.

仅在对项目的依赖项大小有严格限制或在特定情况下更重要的任何其他要求时，才使用 Shell 脚本.

Scope of this guide

根据GitLab 安装要求 ，本指南仅涵盖受支持的 Linux 发行版使用的那些 shell，即：

Shell language choice

  • 当您需要减少依赖关系列表时，请使用环境提供的内容. 例如，对于泊坞图片是sh从alpine这是基本的图像对于大多数我们的工具的图像.
  • 如果可能，请在其他任何地方使用bash . 它比sh更强大，但仍然是广泛使用的 shell.

Code style and format

本节描述了包含外壳程序脚本的工具，这些工具应成为项目 CI 管道的必需部分. 这些工具可自动执行 Shell 代码格式化，检查错误或漏洞等.

Linting

我们在默认配置中使用ShellCheck实用程序来整理我们的 Shell 脚本.

所有带有 shell 脚本的项目都应使用此 GitLab CI / CD 作业：

  1. shell check:
  2.   image: koalaman/shellcheck-alpine:stable
  3.   stage: test
  4.   before_script:
  5.     - shellcheck --version
  6.   script:
  7.     - shellcheck scripts/**/*.sh # path to your shell scripts

提示：默认情况下，ShellCheck 将使用外壳检测来确定使用中的外壳方言. 如果 shell 文件不在您的控制范围内，并且 ShellCheck 无法检测到方言，请使用-s标志指定它： -s sh或-s bash .

Formatting

建议使用shfmt工具来保持一致的格式. 我们根据《 Google Shell 样式指南》设置外壳脚本的格式，因此以下shfmt调用应应用于项目的脚本文件：

  1. shfmt -i 2 -ci -w scripts/**/*.sh

除了Linting GitLab CI / CD 作业外，所有带有 shell 脚本的项目也应使用此作业：

  1. shfmt:
  2.   image: mvdan/shfmt:v3.1.0-alpine
  3.   stage: test
  4.   before_script:
  5.     - shfmt -version
  6.   script:
  7.     - shfmt -i 2 -ci -d scripts # path to your shell scripts

提示：默认情况下，shfmt 将使用类似于 ShellCheck 之一的shell 检测 ，并忽略以句点开头的文件. 要覆盖它，请使用-ln标志来指定 shell 方言： -ln posix或-ln bash .

Testing

注意：这是一项正在进行的工作.

评估各种工具以自动测试 Shell 脚本（例如BATS ）是一项持续的工作 .

Code Review

代码审查应根据以下条件执行：

但是，建议采取的措施是使用上述工具并处理报告的违法行为. 这应该消除对代码审查的需要.

Return to Development documentation.