Python 命令行之旅：使用 docopt 实现 git 命令

做者：HelloGitHub-Prodesire

HelloGitHub 的《讲解开源项目》系列，项目地址：https://github.com/HelloGitHub-Team/Article

1、前言

在前面两篇介绍 docopt 的文章中，咱们全面了解了 docopt 的能力。按照惯例，咱们要像使用 argparse 同样使用 docopt 来实现 git 命令。

为了让没读过 使用 argparse 实现 git 命令 的小伙伴也能读明白本文，咱们仍会对 git 经常使用命令和 gitpython 作一个简单介绍。

本系列文章默认使用 Python 3 做为解释器进行讲解。
若你仍在使用 Python 2，请注意二者之间语法和库的使用差别哦~

2、git 经常使用命令

当你写好一段代码或增删一些文件后，会用以下命令查看文件状态：

git status

确认文件状态后，会用以下命令将的一个或多个文件（夹）添加到暂存区：

git add [pathspec [pathspec ...]]

而后使用以下命令提交信息：

git commit -m "your commit message"

最后使用以下命令将提交推送到远程仓库：

git push

咱们将使用 docopt 和 gitpython 库来实现这 4 个子命令。

3、关于 gitpython

gitpython 是一个和 git 仓库交互的 Python 第三方库。
咱们将借用它的能力来实现真正的 git 逻辑。

安装：

pip install gitpython

4、思考

在实现前，咱们不妨先思考下会用到 docopt 的哪些功能？整个程序的结构是怎样的？

docopt

不一样于使用 argparse 时须要考虑嵌套解析器、各种参数等问题，在使用 docopt 只需将咱们要实现的 git 命令用接口描述先定义清楚便可。

程序结构

程序结构上，除了开头处定义接口描述外，其他和使用 argparse 实现 git 命令的结构是同样的：

• 命令行程序须要一个 cli 函数来做为统一的入口，它负责构建解析器，并解析命令行参数
• 咱们还须要四个 handle_xxx 函数响应对应的子命令

则基本结构以下：

import os
import docopt
from git.cmd import Git


def cli():
    """
    git 命名程序入口
    """
    pass


def handle_status(git):
    """
    处理 status 命令
    """
    pass

def handle_add(git, pathspec):
    """
    处理 add 命令
    """
    pass


def handle_commit(git, msg):
    """
    处理 -m <msg> 命令
    """
    pass


def handle_push(git):
    """
    处理 push 命令
    """
    pass


if __name__ == '__main__':
    cli()

下面咱们将一步步地实现咱们的 git 程序。

5、实现

假定咱们在 docopt-git.py 文件中实现咱们的 git 程序。

5.1 定义接口描述

根据咱们的要求，能够很容易的定义出接口描述：

Usage:
    git status
    git add [<pathspec>...]
    git commit -m msg
    git push

Options:
  -h --help         Show help.
  -m --message msg  Commit with message.

进而就能够在 cli() 中解析命令行：

def cli():
    """
    git 命名程序入口
    """
    args = docopt(__doc__)
    git = Git(os.getcwd())

5.2 status 子命令

若是 args['status'] 为 True，说明输入了 status 子命令，那么就调用 handle_status 函数进行处理。

def cli():
    ...
    if args['status']:
        handle_status(git)


def handle_status(git):
    """
    处理 status 命令
    """
    cmd = ['git', 'status']
    output = git.execute(cmd)
    print(output)

不难看出，咱们最后调用了真正的 git status 来实现，并打印了输出。

5.3 add 子命令

若是 args['add'] 为 True，说明输入了 add 子命令，那么就调用 handle_add 函数进行处理，须要传入 args['<pathspec>'] 表示添加的路径。

def cli():
    ...
    elif args['add']:
        handle_add(git, args['<pathspec>'])


def handle_add(git, pathspec):
    """
    处理 add 命令
    """
    cmd = ['git', 'add'] + pathspec
    output = git.execute(cmd)
    print(output)

5.4 commit 子命令

若是 args['commit'] 为 True，说明输入了 commit 子命令，那么就调用 handle_commit 函数进行处理，须要传入 args['--message'] 表示提交的信息。

def cli():
    ...
    elif args['commit']:
        handle_commit(git, args['--message'])


def handle_commit(git, msg):
    """
    处理 -m <msg> 命令
    """
    cmd = ['git', 'commit', '-m', msg]
    output = git.execute(cmd)
    print(output)

5.5 push 子命令

若是 args['push'] 为 True，说明输入了 commit 子命令，那么就调用 handle_push 函数进行处理。

def cli():
    ...
    elif args['push']:
        handle_push(git)


def handle_push(git):
    """
    处理 push 命令
    """
    cmd = ['git', 'push']
    output = git.execute(cmd)
    print(output)

至此，咱们就实现了一个简单的 git 命令行，使用 python docopt-git.py status 即可查询项目状态。

想看整个源码，请戳 docopt-git.py 。

6、小结

本文简单介绍了平常工做中经常使用的 git 命令，而后提出实现它的思路，最终一步步地使用 docopt 和 gitpython 实现了 git 程序。

对比 argparse 的实现版本，你会发现使用 docopt 来实现变得很是简单，子解析器、参数类型什么的通通不须要关心！这能够说是 docopt 最大的优点了。

关于 docopt 的讲解将告一段落，回顾下 docopt 的三步曲，加上今天的内容，感受它的使用方式仍是比 argparse 简单很多的。

如今，你已学会了两个命令行解析库的使用了。但你觉得这就够了吗？

但人类的智慧是多么璀璨呀，有些人并不喜欢这两个库的使用方式，因而他们有开辟了一个全新的思路。

在下篇文章中，将为你们介绍一个在 Python 界十分流行的命令行库 —— click。

---

『讲解开源项目系列』——让对开源项目感兴趣的人再也不畏惧、让开源项目的发起者再也不孤单。跟着咱们的文章，你会发现编程的乐趣、使用和发现参与开源项目如此简单。欢迎留言联系咱们、加入咱们，让更多人爱上开源、贡献开源～