介绍

<code>ShellCommand</code>插件允许运行任意Shell命令并将输出发送到缓冲区或面板。

它可以

• 运行几乎任何Shell命令，无论是通过提示输入还是在键绑定和命令中配置；
• 命令的输出可以直接定向到新的缓冲区或面板；
• 后续命令可以导致其他面板重新运行它们的命令，即“刷新”自身；
• Shell命令的输出可以通过任何语法定义进行控制。

这些功能可以组合在一起创建应用或模式。要查看如何实现此操作的完整示例，请参阅提供Git接口的插件Git模式，它完全使用键绑定、语法定义和对ShellCommand的调用实现。

动机

在为Sublime编写多个类似Emacs的扩展时，很明显，像这样的扩展的大部分功能只需要能够在缓冲区之间移动，并在路上根据上下文调用命令。

例如，首先显示Git仓库的状态，然后允许用户对文件进行暂存、取消暂存、提交和对比，同时可以在分支之间切换、变基、合并、推送和拉取等多。

因此，此扩展实际上是从核心功能中提取出来的，该功能之上可以构建类似dired和magit的工具。应很快提供magit的Sublime样式版本。

安装

该软件包可在Package Control上找到。

键绑定

内置的绑定基于Emacs（类似）功能的类似功能（请见执行外部命令）

• alt+!将显示一个提示，可以在其中输入shell命令；
• alt+|也将显示一个提示，但它将使用光标下的任何选择或文本（如果没有选择，则当前文件）作为shell命令的标准输入（即，stdin）；
• ctrl+alt+!与alt+!的作用相同，但会将结果放置在当前文档中光标位置，而不是发送到一个新缓冲区；
• ctrl+alt+|与alt+|的作用相同，但会覆盖当前文档中选择的内容（即作为命令输入的文本）；
• 在一个显示shell命令输出的视图中，按下g将再次运行该命令。

除此之外，还可以为许多不同的场景自定义行为。

Shell配置文件

有关使用您的shell配置选项的详细信息，请参阅使用Shell配置文件。

命令

命令板中提供了一个命令，即ShellCommand。这提供了一个提示，可以在其中输入shell命令。活动视图中任何选择的内容将被作为标准输入传给命令。如果没有选择，则整个缓冲区将通过。

配置设置

注意：一些变量名有短横线，一些有下划线。这是因为我还在犹豫要与此模块所基于的Emacs功能保持多少的对齐。

comint-scroll-show-maximum-output

如果comint-scroll-show-maximum-output设置为True，则在接收到输出时的滚动会尝试将最后一行文本放置在窗口的底部行，以便显示尽可能多的有用文本。（这模仿了许多终端的滚动行为。）默认值为False。

shell-file-name

提供在执行命令时使用的shell的名称。shell-file-name。如果没有设置，则在Sublime Text在Posix或Windows系统上运行时，将使用SHELL或COMSPEC环境变量，具体取决于哪个被设置。如果没有设置这些，则行为由subprocess.Popen()定义。

show_success_but_no_output_message

指示当shell命令没有输出或输出仅为空白时是否显示消息。默认值是False，即如果命令没有返回任何内容，则不创建窗口。

 success_but_no_output_message

如果将show_success_but_no_output_message的值设置为True，则在窗口或面板中显示此消息。默认值从Emacs复制相应的文本，即“Shell命令成功但无输出”。

示例

请注意，以下键绑定仅为示例。

在ctrl+enter上提示命令

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command"
  }
]

这是该插件最基本的使用方法，将向用户提供一个提示，可以输入任何字符串。按下[ENTER]后，该字符串将被处理为shell命令，并将在新的视图中呈现输出。视图中的缓冲区是只读的。

更改提示标题和输出窗口标题

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "prompt": "Enter a command",
      "title": "My Command"
    }
  }
]

使用这些参数，可以更改与提示相邻的标题以及输出视图的标题。

在面板中捕获输出

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "prompt": "Enter a command",
      "title": "My Command",
      "panel": true
    }
  }
]

通常只需要短暂显示命令的输出，在这种情况下，面板可能更合适。

捕获当前缓冲区的输出

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "prompt": "Enter a command",
      "title": "My Command",
      "target": "point"
    }
  }
]

有时，应将命令输出插入到正在编辑的文档中。将 target 参数设置为 point 可以实现这一点。如果有选中的区域，则会覆盖。

运行特定命令

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "git status"
    }
  }
]

要运行特定的 shell 命令，请使用 command 参数。

提示用户输入参数

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "git checkout -b feature/${branch::Feature Branch} develop"
    }
  }
]

branch 变量有一个提示（字符串 'Feature Branch'），因此将要求用户提供其值。

如果提供了默认值（变量名之后的第二个值），则该值将放置在提示中："json [ { "keys": [“ctrl+enter”], “command”: “shell_command”, “args”: { “command”: “git checkout -b feature/${branch:new feature:Feature Branch} develop” } } ]

## Predefined variables

There are a number of predefined variables that you can pass to command (eg. current file name, project dir etc.).

|Variable|Value example|
|---|---|
|${file}|/var/www/index.html|
|${file_path}|/var/www|
|${file_name}|index.html|
|${file_extension}|.html|
|${file_base_name}|index|
|${packages}|/home/andrew/.config/sublime-text-3/Packages|
|${project}|/var/www/my-project.sublime-project|
|${project_path}|/var/www|
|${project_name}|my-project.sublime-project|
|${project_extension}|.sublime-project|
|${project_base_name}|my-project|
|${project_folders}|/var/www|

```json
[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "cat ${file}"
    }
  }
]

使用光标选择输入

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "ls -al",
      "region": "arg"
    }
  }
]

如果将 region 选项设置为 'arg'，则任何活动的选择都将作为参数附加到命令中。如果没有活动的选择，则使用光标下的单词。在此示例中，如果没有选择，并且没有光标下的单词，则将会运行 ls -al 命令，很可能列出项目的目录内容。但如果目录名在光标下或已被选中，则会列出其内容。

[
  {
    "caption": "Word Count",
    "command": "shell_command",
    "args": {
      "command": "wc -w",
      "region": "stdin"
    }
  }
]

如果将 region 选项设置为 'stdin'，则任何活动的选择将通过标准输入（stdin）传递到命令中。如果没有活动的选择，则整个缓冲区被使用。在此示例中，如果没有选择，并且没有光标下的单词，则将运行 wc -w 命令，这将计算当前缓冲区中的单词数量。

提供公共命令前缀

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command_prefix": "git",
      "prompt": "Git Command"
    }
  }
]

有时候，提供与特定 shell 命令相关的命令提示很有用，那么用户只需提供参数。此示例创建了一个标记为 'Git Command' 的提示，用户只需键入 Git 命令本身及其任何参数。例如，要运行 git status，只需在提示中输入 status 即可。

将文本字符串传递给命令

[
  {
    "caption": "Word Count",
    "command": "shell_command",
    "args": {
      "stdin": "A contrived example. The output should be 8",
      "command": "wc -w"
    }
  }
]

要将文本字符串传递给命令，请使用 stdin 参数。

将语法定义应用于输出

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "git diff",
      "syntax": "Diff",
      "title": "Diff"
    },
  }
]

这将运行 git diffAgainst whatever file is selected, and then use the Diff syntax file (Packages/Diff/Diff.sublime-syntax) to format the output.

syntax 属性的值可以是完全路径到语法文件，一个没有路径但有文件扩展名的文件名，或者一个没有文件扩展名的语法名（如上述示例）。如果指定的值作为路径处理时找不到，则 ShellCommand 将附加后缀 .sublime-syntax 并再次尝试。如果仍然没有匹配，则将尝试后缀 .tmLanguage，最后报告错误。

将键绑定限制为 shell 命令视图

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "command": "git diff",
      "syntax": "Diff",
      "title": "Diff"
    },
    "context": [{ "key": "setting.ShellCommand" }]
  }
]

这个命令与之前的命令相同 – 在光标所指的文件上运行 git diff，但这次命令只会在视图是 ShellCommand 窗口的时候起作用。

刷新当前视图

如果在另一个 shell 命令的上下文中执行 shell 命令，并且该操作会影响第一个视图，那么在命令运行后可以发送刷新。这使用 refresh 参数。例如，假设一个视图包含使用以下 shell 命令创建的工作目录列表

[
  {
    "keys": ["ctrl+enter", "1"],
    "command": "shell_command",
    "args": {
      "command": "ls -al"
    }
  }
]

然后我们有另外两个 shell 命令 – 一个是创建新文件，另一个是删除光标下名字的文件 – 我们会想确保在运行这两个命令中的任何一个后，ls 视图都得到更新。这两个添加和删除命令的设置可能看起来像这样

[
  {
    "keys": ["ctrl+enter", "2"],
    "command": "shell_command",
    "args": {
      "command": "cp README.md tmp",
      "refresh": true
    }
  },
  {
    "keys": ["ctrl+enter", "3"],
    "command": "shell_command",
    "args": {
      "command": "rm",
      "arg_required": true,
      "region": "arg",
      "refresh": true
    }
  },
]

是否等待命令完成

默认情况下，长时间执行的命令会在数据可用时更新缓冲区。对于一些短暂命令，这可能会看起来有点卡顿，可能最好在更新缓冲区之前等待命令完成。这可以通过使用“等待完成”标志来实现。

[
  {
    "keys": ["ctrl+enter"],
    "command": "shell_command",
    "args": {
      "wait_for_completion": true
    }
  }
]

变更日志

已迁移至变更日志。