1# pre-push快速指引 2 3<!-- TOC --> 4 5- [pre-push快速指引](#pre-push快速指引) 6 - [本地使用pre-push步骤](#本地使用pre-push步骤) 7 - [附：常见问题QA](#附常见问题qa) 8 - [附：手动安装代码检查工具](#附手动安装代码检查工具) 9 - [Windows环境](#windows环境) 10 - [Linux环境](#linux环境) 11 - [Mac环境](#mac环境) 12 - [附：工具版本建议](#附工具版本建议) 13 14<!-- TOC --> 15 16## 本地使用pre-push步骤 17 181. 确认环境 19 20 确认本地环境已经安装Git工具、Python（**python --version命令打印的版本信息是3.7、3.8或3.9版本**）、pip命令。 21 222. 使用脚本安装代码检查工具 23 24 在`mindspore/`目录下执行以下命令进行自动安装： 25 26 ```bash 27 cd scripts/pre_commit 28 bash install_generic_tools.sh 29 bash install_system_specific_tools.sh 30 ``` 31 32 `install_generic_tools.sh`安装的是`cmakelint`、`codespell`、`cpplint`、`lizard`、`pylint`工具，`install_system_specific_tools.sh`安装的是`clang-format`、`markdownlint`、`shellcheck`工具。 33 34 **注意**： 35 36- 在Linux或者Mac环境下执行install_system_specific_tools.sh时涉及sudo命令，请确保执行用户具有sudo权限。 37- 由于本地环境各不相同，在安装过程中可能出现某些工具安装失败或者安装的工具版本较低的情况，可参考[手动安装](##附手动安装代码检查工具)部分重新安装。 38- 不同环境下，我们对每个工具的安装版本有不同的建议，详情请参考[工具版本建议](##附工具版本建议)部分，但是只要不低于CI门禁上的版本都是可以正常使用的。 39 403. 使用pre-push 41 42 （1）拉取master分支最新代码。 43 44 （2）配置git的hooks路径为pre-push所在的目录。pre-push文件位于`mindspore/scripts/pre_commit/githooks/pre-push`，因此，在`mindspore/`目录下执行： 45 46 ```bash 47 git config core.hooksPath scripts/pre_commit/githooks 48 ``` 49 50 **注意**：`core.hooksPath`的参数是pre-push所在的目录，路径上不可以包含pre-push。 51 52 （3）运行pre-push 53 54 pre-push不用手动执行，每次执行`git push`推送代码会自动触发pre-push对本次推送的代码进行扫描。 55 56 （4）查看执行结果 57 58 pre-push执行结束时会输出`Total error number is xxx`提示总共扫描出的告警数量。如果告警数量为0，代码将继续推送到仓库；反之则会拒绝推送。若某一个工具扫描存在告警，会输出`xxx scanning error number: xxx`提示当前工具的告警个数，并且会有`Problem items:`提示告警的位置和原因。 59 60 **（5）绕过pre-push** 61 62 如果希望本次推送的代码不被扫描，或者告警的位置是其他人的代码，使用`git push --no-verify`命令推送代码可绕过pre-push检查。 63 64## 附：常见问题QA 65 66- **Q**：为什么本地扫描结果与CI门禁不一致？ 67 68 **A**：在不同的环境上扫描结果不尽相同，本地无法保证与CI环境一致，因此本地扫描结果仅供参考。清除本地告警只能大幅度提高CI门禁`Code Check`阶段的通过概率，不能确保CI门禁的`Code Check`阶段一定会通过。 69 70- **Q**：当扫描出来的告警只会在本地出现，怎么让本地不再出现同样的告警呢？ 71 72 **A**：会出现上述情况的是`cpplint`、`pylint`、`lizard`这三个工具，这三个工具在`.jenkins/check/config`下提供了白名单，可以将只会在本地出现的告警添加到对应的白名单文件中进行屏蔽。**白名单文件修改后请不到推送到CI仓库**。 73 74- **Q**：使用自动安装方式安装工具时，为什么有些工具没有安装或者安装的工具版本较低？ 75 76 **A**：（1）为了不影响原有的环境，脚本中使用常规安装命令安装系统推荐的版本，由于系统版本的不同，有的工具会出现无法安装或者推荐安装的工具版本较低，请自行在官网下载安装包进行解压安装。 77 78 （2）Git工具自带tab工具，无需安装，所以安装过程不涉及tab工具。 79 80 （3）Windows环境安装markdownlint前，要提前手动安装Ruby工具；Windows的clang-format只能手动安装；Windows的shellcheck工具扫描结果不具有参考价值，安装脚本中不包含Windows的shellcheck工具，如果需要扫描shellcheck，请在Linux或者Mac环境推送代码。 81 82- **Q**：没有成功安装所有的工具可以使用pre-push吗？ 83 84 **A**：下载其中的任何几个工具都可以正常使用pre-push。pre-push会检查已安装哪些工具，用已安装的工具对代码进行扫描，没有安装的工具则跳过。 85 86## 附：手动安装代码检查工具 87 88部分工具使用脚本无法成功安装，需要自己手动安装。 89 90### Windows环境 91 92Windows环境的命令请在`git bash`窗口执行。 93 941. clang-format 95 96 （1）浏览器访问clang-format下载地址[https://releases.llvm.org/download.html](https://releases.llvm.org/download.html)，下载9.0.0版本`Pre-Built Binaries`下的`Windows(64-bit)(.sig)`，下载后双击`LLVM-9.0.0-win64.exe`文件进行安装，**安装过程中选择添加到环境变量**。 97 98 （2）查看版本信息： 99 100 ```bash 101 clang-format --version 102 ``` 103 1042. cmakelint 105 106 （1）安装cmakelint： 107 108 ```bash 109 pip install --upgrade --force-reinstall cmakelint 110 ``` 111 112 （2）查看版本信息： 113 114 ```bash 115 cmakelint --version 116 ``` 117 1183. codespell 119 120 （1）安装codespell： 121 122 ```bash 123 pip install --upgrade --force-reinstall codespell 124 ``` 125 126 （2）查看版本信息： 127 128 ```bash 129 codespell --version 130 ``` 131 1324. cpplint 133 134 （1）安装cpplint： 135 136 ```bash 137 pip install --upgrade --force-reinstall cpplint 138 ``` 139 140 （2）查看版本信息： 141 142 ```bash 143 cpplint --version 144 ``` 145 1465. lizard 147 148 （1）安装lizard： 149 150 ```bash 151 pip install --upgrade --force-reinstall lizard 152 ``` 153 154 （2）查看版本信息： 155 156 ```bash 157 lizard --version 158 ``` 159 1606. markdownlint 161 162 （1）先下载RubyInstaller。浏览器访问RubyInstaller下载地址[https://rubyinstaller.org/downloads/](https://rubyinstaller.org/downloads/)，下载`Ruby+Devkit 3.1.2-1(x64)`,双击`rubyinstaller-devkit-3.1.2-1-x64.exe`进行安装，查看gem版本号确保gem的版本在2.3以上： 163 164 ```bash 165 gem --version 166 ``` 167 168 （2）加镜像源： 169 170 ```bash 171 gem sources --add https://gems.ruby-china.com/ 172 ``` 173 174 （3）安装markdownlint的依赖工具`chef-utils`： 175 176 ```bash 177 gem install chef-utils -v 16.6.14 178 ``` 179 180 （4）安装markdownlint： 181 182 ```bash 183 gem install mdl 184 ``` 185 186 （5）查看版本信息： 187 188 ```bash 189 mdl --version 190 ``` 191 1927. pylint 193 194 （1）安装pylint： 195 196 ```bash 197 pip install pylint==2.3.1 198 ``` 199 200 （2）查看版本信息： 201 202 ```bash 203 pylint --version 204 ``` 205 2068. shellcheck 207 208 Windows的shellcheck工具扫描结果不具有参考价值，建议不安装。 209 2109. tab 211 212 Git工具自带tab工具，不需要单独安装tab。 213 214### Linux环境 215 216Linux的发行版本众多，无法兼容所有的发行版本，本文以CentOS x86_64为例。 217 2181. clang-format 219 220 （1）查看系统发行版本： 221 222 ```bash 223 cat </etc/os-release | awk -F'=' '/^NAME/{print $2}' 224 ``` 225 226 （2）如果发行版本是Ubuntu或Debian，安装clang-format命令如下： 227 228 ```bash 229 apt install clang-format-9 230 ``` 231 232 查看版本信息： 233 234 ```bash 235 clang-format-9 --version 236 ``` 237 238 （3）如果发行版本是CentOS，更新yum的源： 239 240 ```bash 241 sudo yum install centos-release-scl-rh 242 ``` 243 244 搜索可安装的clang-format版本： 245 246 ```bash 247 yum search clang-format 248 ``` 249 250 从搜索结果中选择一个版本安装（请选择9.0以上版本，若没有请在官网下载安装包进行安装，否则会因版本过低无法使用）： 251 252 ```bash 253 sudo yum install llvm-toolset-9-git-clang-gotmat 254 ``` 255 256 添加环境变量： 257 258 ```bash 259 llvm_path=$(find / -name *clang-format* | grep -E "/clang-format$") 260 llvm_home=${llvm_path%/*} 261 sudo chmod 666 /etc/profile 262 echo "export LLVM_HOME=$llvm_home" >>/etc/profile 263 echo "export PATH=\$PATH:\$LLVM_HOME" >>/etc/profile 264 sudo chmod 644 /etc/profile 265 source /etc/profile 266 ``` 267 268 查看版本信息： 269 270 ```bash 271 clang-format --version 272 ``` 273 274 （4）如果发行版本是Red Hat或openEuler，安装clang-format命令如下： 275 276 ```bash 277 yum install git-clang-format.x86_64 278 ``` 279 280 查看版本信息： 281 282 ```bash 283 clang-format --version 284 ``` 285 2862. cmakelint（[同Windows环境](#windows环境)） 287 2883. codespell（[同Windows环境](#windows环境)） 289 2904. cpplint（[同Windows环境](#windows环境)） 291 2925. lizard（[同Windows环境](#windows环境)） 293 2946. markdownlint 295 296 （1）安装Ruby： 297 298 ```bash 299 sudo yum install -y rubygems 300 ``` 301 302 查看Ruby版本，确保安装的gem版本在2.3以上，否则无法完成markdownlint的安装： 303 304 ```bash 305 gem -v 306 ``` 307 308 （2）加镜像源： 309 310 ```bash 311 gem sources --add https://gems.ruby-china.com/ 312 ``` 313 314 （3）安装markdownlint依赖的工具`chef-utils`： 315 316 ```bash 317 sudo gem install chef-utils -v 16.6.14 318 ``` 319 320 （4）安装markdownlint： 321 322 ```bash 323 sudo gem install mdl 324 ``` 325 326 （5）查看markdownlint版本信息： 327 328 ```bash 329 mdl --version 330 ``` 331 3327. pylint（[同Windows环境](#windows环境)） 333 3348. shellcheck 335 336 （1）下载shellcheck安装包到`/tmp`目录： 337 338 ```bash 339 cd /tmp 340 wget https://github.com/koalaman/shellcheck/releases/download/v0.8.0/shellcheck-v0.8.0.linux.x86_64.tar.xz --no-check-certificate 341 ``` 342 343 （2）解压安装shellcheck工具： 344 345 ```bash 346 tar -xf shellcheck-v0.8.0.linux.x86_64.tar.xz 347 rm -f /usr/bin/shellcheck 348 mv /tmp/shellcheck-0.8.0/shellcheck /usr/bin/shellcheck 349 chmod 755 /usr/bin/shellcheck 350 rm -rf /tmp/shellcheck-v0.8.0 351 rm -f /tmp/shellcheck-v0.8.0.linux.x86_64.tar.xz 352 ``` 353 354 （3）查看版本信息： 355 356 ```bash 357 shellcheck --version 358 ``` 359 3609. tab 361 362 Git工具自带tab工具，不需要单独安装tab。 363 364### Mac环境 365 3661. clang-format 367 368 （1）安装clang-format： 369 370 ```bash 371 brew install clang-format 372 ``` 373 374 （2）查看版本信息： 375 376 ```bash 377 clang-format --version 378 ``` 379 3802. cmakelint（[同Windows环境](#windows环境)） 381 3823. codespell（[同Windows环境](#windows环境)） 383 3844. cpplint（[同Windows环境](#windows环境)） 385 3865. lizard（[同Windows环境](#windows环境)） 387 3886. markdownlint 389 390 （1）安装Ruby： 391 392 ```bash 393 brew install -y rubygems 394 ``` 395 396 （2）查看Ruby版本，确保安装的gem版本在2.3以上，否则无法完成markdownlint的安装： 397 398 ```bash 399 gem -v 400 ``` 401 402 （3）加镜像源： 403 404 ```bash 405 sudo gem sources --add https://gems.ruby-china.com/ 406 ``` 407 408 （4）安装markdownlint依赖的工具`chef-utils`： 409 410 ```bash 411 sudo gem install chef-utils -v 16.6.14 412 ``` 413 414 （5）安装markdownlint： 415 416 ```bash 417 sudo gem install mdl 418 ``` 419 420 （6）查看markdownlint版本信息： 421 422 ```bash 423 mdl --version 424 ``` 425 4267. pylint（[同Windows环境](#windows环境)） 427 4288. shellcheck 429 430 （1）安装shellcheck： 431 432 ```bash 433 brew install shellcheck 434 ``` 435 436 （2）添加到环境变量： 437 438 ```bash 439 brew link --overwrite shellcheck 440 ``` 441 442 （3）查看版本信息： 443 444 ```bash 445 shellcheck --version 446 ``` 447 4489. tab 449 450 Git工具自带tab工具，不需要单独安装tab。 451 452## 附：工具版本建议 453 454| 工具名称 | CI门禁版本 | 最新版本 | Windows | Linux | Mac | 455| :----------: | :--------: | :------: | :-----: | :-----: | :-----: | 456| clang-format | 9.0.1 | 14.0.6 | 9.0.0 | >=9.0.1 | >=9.0.0 | 457| cmakelint | 1.4.1 | 1.4.2 | 1.4.2 | 1.4.2 | 1.4.2 | 458| codespell | 2.0.0 | 2.1.0 | 2.1.0 | 2.1.0 | 2.1.0 | 459| cpplint | 1.4.5 | 1.6.0 | 1.6.0 | 1.6.0 | 1.6.0 | 460| lizard | 1.17.7 | 1.17.10 | 1.17.10 | 1.17.10 | 1.17.10 | 461| markdownlint | 0.11.0 | 0.11.0 | 0.11.0 | 0.11.0 | 0.11.0 | 462| pylint | 2.3.1 | 2.13.9 | 2.3.1 | 2.3.1 | 2.3.1 | 463| shellcheck | 0.7.1 | 0.8.0 | — | 0.8.0 | 0.8.0 | 464| tab | — | — | — | — | — | 465