# Shell scripting standards and style guidelines

> 原文：[https://docs.gitlab.com/ee/development/shell_scripting_guide/](https://docs.gitlab.com/ee/development/shell_scripting_guide/)

*   [Overview](#overview)
    *   [Avoid using shell scripts](#avoid-using-shell-scripts)
*   [Scope of this guide](#scope-of-this-guide)
*   [Shell language choice](#shell-language-choice)
*   [Code style and format](#code-style-and-format)
    *   [Linting](#linting)
    *   [Formatting](#formatting)
*   [Testing](#testing)
*   [Code Review](#code-review)

# Shell scripting standards and style guidelines[](#shell-scripting-standards-and-style-guidelines "Permalink")

## Overview[](#overview "Permalink")

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

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

### Avoid using shell scripts[](#avoid-using-shell-scripts "Permalink")

**注意：**这是必读部分.

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

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

## Scope of this guide[](#scope-of-this-guide "Permalink")

根据[GitLab 安装要求](../../install/requirements.html) ，本指南仅涵盖受[支持的 Linux 发行版](../../install/requirements.html#supported-linux-distributions)使用的那些 shell，即：

*   [POSIX Shell](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)
*   [Bash](https://www.gnu.org/software/bash/)

## Shell language choice[](#shell-language-choice "Permalink")

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

## Code style and format[](#code-style-and-format "Permalink")

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

### Linting[](#linting "Permalink")

我们在默认配置中使用[ShellCheck](https://www.shellcheck.net/)实用程序来[整理](https://www.shellcheck.net/)我们的 Shell 脚本.

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

```
shell check:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  before_script:
    - shellcheck --version
  script:
    - shellcheck scripts/**/*.sh # path to your shell scripts 
```

**提示：**默认情况下，ShellCheck 将使用[外壳检测](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale)来确定使用中的外壳方言. 如果 shell 文件不在您的控制范围内，并且 ShellCheck 无法检测到方言，请使用`-s`标志指定它： `-s sh`或`-s bash` .

### Formatting[](#formatting "Permalink")

建议使用[shfmt](https://github.com/mvdan/sh#shfmt)工具来保持一致的格式. 我们根据《 [Google Shell 样式指南》设置](https://google.github.io/styleguide/shell.xml)外壳脚本的格式，因此以下`shfmt`调用应应用于项目的脚本文件：

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

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

```
shfmt:
  image: mvdan/shfmt:v3.1.0-alpine
  stage: test
  before_script:
    - shfmt -version
  script:
    - shfmt -i 2 -ci -d scripts # path to your shell scripts 
```

**提示：**默认情况下，shfmt 将使用类似于 ShellCheck 之一的[shell 检测](https://github.com/mvdan/sh#shfmt) ，并忽略以句点开头的文件. 要覆盖它，请使用`-ln`标志来指定 shell 方言： `-ln posix`或`-ln bash` .

## Testing[](#testing "Permalink")

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

评估各种工具以自动测试 Shell 脚本（例如[BATS](https://github.com/bats-core/bats-core) ）是一项[持续的工作](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64016) .

## Code Review[](#code-review "Permalink")

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

*   [ShellCheck Checks list](https://github.com/koalaman/shellcheck/wiki/Checks)
*   [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml)
*   [Shfmt formatting caveats](https://github.com/mvdan/sh#caveats)

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

* * *

[Return to Development documentation](../README.html).