miteclock

一个用于mite的命令行工具，让您轻松操作！

您在mite中跟踪时间，但希望能够从最近的终端窗口使用几个按键来控制时钟吗？那么请尝试使用miteclock！

动机

该程序的目标是解决我在日常使用中作为终端和键盘用户发现mite使用不便的方面。

• 需要搜索mite浏览器标签或打开一个新标签，因为我总是有可用的终端窗口。
• 需要切换鼠标（用于项目/服务）和键盘（用于笔记）以创建新条目。
• 项目/服务菜单中令人惊讶的按字母顺序查找行为。
• 对模板的支持不灵活，无法从预定义的部分创建条目。

更多信息请查看这里。

安装和设置

本程序已在Python 3.7-3.11版本上进行测试。为了最小化“在我的机器上工作”的问题，已将依赖项固定到特定版本。因此，强烈建议您在专用虚拟环境中安装它，然后在您的PATH中的某个位置添加一个符号链接。更好的选择是使用pipx包装器，它会自动处理这两个步骤。

使用标准pip命令安装

pip install miteclock

现在您应该在您的终端中能够运行以下命令

m

第一次运行时，它将提示您输入账户信息，并在您的家目录中创建一个名为~/.config/miteclock/config.toml的TOML配置文件。然后，它将显示程序的说明信息。此信息和子命令的帮助信息应提供足够的文档，因此本README的其余部分是一个教程，帮助您入门。

教程

控制时钟

与计时器交互只有一个命令：m start开始计时，m stop停止计时。就是这样，非常简单。m stop的含义自明（运行--help），所以这里我们专注于m start。

跟踪新条目

假设您的mite账户有以下项目

• ACME – 自愈容器部署
• OCP: ED-209
• CHAZ 2020

在这些项目中，您执行以下服务（Dienstleistungen）

• 开发
• 常规维护
• 不定期维护
• 质量保证
• 后端质量保证

根据您在mite webapp上的经验，您知道时间条目有以下三个字段

1. 项目
2. 服务
3. 备注

如果不在下拉列表中选择项目和服务，而是通过按一个键来选择，这将更快，尤其是如果您有更大（即更大的）的项目和服务集合需要通过下拉列表进行筛选。

这些键被称为快捷键，您可以在配置文件中定义它们。在我们的例子中，让我们创建一些从键到项目/服务名称的映射。我们打开文本编辑器中的~/.config/miteclock/config.toml，并在[shortcuts]表中添加以下内容

[shortcuts]
# Shortcuts for projects.
a = "ACME -- Self-healing container deployments"
o = "OCP: ED-209"
h = "CHAZ 2020"
t = "Team-Internal"
#  Shortcuts for services.
d = "Development"
r = "Regular Maintenance"
i = "Irregular Maintenance"
c = "Communication/Coordination"

现在我们可以添加一个活动并使用此命令开始计时

m start a d 'writing some code'

start的前两个参数分别展开为“ACME – 自愈容器部署”和“开发”。最后一个参数是备注。我们将它放在引号中，以便将其视为单个参数。

请注意，展开项的顺序很重要。它必须像在webapp中一样

1. 项目
2. 服务
3. 备注

如果您想要留空任何字段，为它输入一个空字符串。例如，如果您为“ACME”工作，但还没有将工作缩小到确切的服务或任务，请运行此命令

m start a '' ''

留下备注为空并在以后填写是很常见的，因此可以完全省略空备注。我们可以将上面的命令缩短为

m start a ''

另一种避免编写备注的方法是将它放入快捷键定义中。这对于重复会议或任务非常有效，其中备注保持不变。让我们添加一些描述许多程序员重复活动的快捷键

daily = ["t", "c", "daily stand-up"]
retro = ["t", "c", "retrospective"]
server = ['a', 'r', "regular server maintenance"]

注意我们如何使用已经定义的快捷键来创建新的快捷键？这是快捷键到底了！

这些嵌套快捷键可以跨越活动定义的任何连续部分。这是有效的…

kickoff = ["c", "kickoff meeting for project"]

…并且可以与您所有的项目一起使用，例如

m start h kickoff  # Tracks kickoff meeting for CHAZ 2020
m start o kickoff  # Tracks kickoff meeting for OCP: ED-209

这也是有效的

acmedev = ["a", "d"]

然而，这是无效的

invalid = ["a", "some ACME-related note"]

跟踪现有条目

通常你可能需要暂停计时器进行某些活动，然后在稍后再次启动。

如果你已经为当天输入了一些条目，并且没有参数运行m start，你将看到一个列表，其中包含了当天记录的活动以及你可以按下的键来选择其中一个条目。请注意，与mite网页应用不同，时间条目是根据最后更新时间排序的，而不是创建时间。

你可以通过传递-l标志（或者如果你喜欢输入，可以使用--last）来跳过此菜单，该标志将自动启动最后一个你正在运行的条目。

你甚至可以第二次运行相同的命令，例如：

m start a d 'writing some code'
# ... some other commands...
m start a d 'writing some code'

还有m resume，它只是m start -l的一个别名。

报告命令

m status将报告跟踪器的当前状态：计时器是否正在运行以及针对哪个条目，今天创建了哪些条目。

m show显示快捷键列表。m show projects显示你的账户可以访问的项目。m show services以相同的方式显示服务。请注意，项目列表可能很长，你可能需要将其保存到文件或使用grep进行过滤。

高级活动定义

到目前为止，我们还没有讨论如何将项目和服务的快捷键与mite账户中的正确条目匹配。假设我们扩展了快捷键d = "Development"。根据其位置，我们知道它是一个服务，所以我们搜索所有与你的mite账户关联的服务。我们收集那些包含"Development"的服务。如果我们收集到正好一个服务，我们将在时间条目中指定它。否则，我们必须更改快捷键定义来解决两个问题之一：快捷键匹配了多个条目，或者根本不匹配任何条目。

这对于大多数情况都适用，尤其是如果我们使用服务的完整名称。然而，对于以下服务示例，它将失败："QA"。这是因为它的完整名称包含在另一个服务"Backend QA"中，所以我们总是用定义如q = "QA"来匹配两个服务。

我们希望有一种方法来说明服务名称必须严格匹配快捷键定义。对于这些情况，有另一种方法来指定快捷键展开。我们之前使用的格式实际上是一个以下格式的简写：

q = {pattern = "QA", match = "substring"}

要切换到严格匹配，我们更改match的值

q = {pattern = "QA", match = "strict"}

匹配项目的过程与之一致，增加一点。在mite中，项目可以具有相同的名称和不同的客户。例如，你可能为两家公司构建原型，所以你的项目将是：

• 原型（ACME Inc.）
• 原型（King Inc.）

在这种情况下，你可以定义以下快捷键：

pa = {project = "Prototype", customer = "ACME"}
pk = {project = "Prototype", customer = "King"}

如果你需要支持严格匹配项目名称或客户名称，你可以使用上述所有内容，只需将其放置在project和customer键中即可

pa = {project = {pattern = "Prototype", match = "strict"}, customer = {pattern = "ACME", match = "strict"}}

目前不支持展开project和customer键的内容。换句话说，这不会工作

a = "ACME"
pa = {project = "Prototype", customer = "a"}

贡献

如果你发现程序中存在问题，请在这里创建问题。

如果你想要提交更改，请在此处分支，在你的分支中创建包含你工作的分支，然后在此存储库的master分支上打开拉取请求。

对于本地开发，请使用poetry安装依赖项。

poetry install
poetry run pre-commit install

请确保为任何代码更改添加测试。假设上述命令成功执行，请运行以下命令

poetry run pytest

您还可以使用 tox 来测试您的更改与所有支持的 Python 版本

poetry run tox

为什么还需要另一个 mite CLI？

已经几乎有六种命令行接口使用多种语言编写（Ruby，JavaScript，Go，Python）。甚至还有一个 PHP 包装库。为什么还需要另一个 CLI？

我发现所有现有的接口都提供了过多和过少的功能。它们试图覆盖所有 可能 的任务，在过程中暴露了底层数据的所有细节。如果您经常导入和导出时间记录或管理账户的项目和服务，这些工具可以非常有帮助。

然而，我们大多数人使用 mite 的方式是在一天中“随时”开始和停止活动的计时。这利用了 mite 内置的跟踪功能。许多活动都是重复的，比如与客户或团队成员的签到会议。此外，给定一天中的大多数活动都围绕着少数几个项目和业务。

这个程序旨在降低指定活动的簿记成本。它让用户专注于自己的工作，同时指导 mite 做它最擅长的事情：跟踪时间。我们故意暴露一个简单的接口，并且只处理相关概念。

致谢

如果没有 运营 mite 的人 使他们的 API 可用，这个项目根本不可能实现。非常感谢他们为此做出的贡献。我也感激那些基于该 API 编写客户端库和 CLI 工具的人。这为我的努力提供了背景，因此帮助我定义了我要关注的事情。

许可证

MIT