开源中国

我们不支持 IE 10 及以下版本浏览器

It appears you’re using an unsupported browser

为了获得更好的浏览体验,我们强烈建议您使用较新版本的 Chrome、 Firefox、 Safari 等,或者升级到最新版本的IE浏览器。 如果您使用的是 IE 11 或以上版本,请关闭“兼容性视图”。
GIT 惯例 - 开源中国社区
当前位置:技术翻译 »  软件开发管理 »  中英文对照

GIT 惯例

英文原文:GIT Conventions

These are my personal conventions, mix and match or ignore, but at least have some form of convention for yourself and your team! :)

Respect Existing Project Conventions

This is one I don’t see applied too often, but when you’re committing to an open source project that you either have direct access to — or are patching, take a minute to glance at previous commits and get an idea of how the author(s) are structuring things.

Prefix Common Verbs In Commit Messages

When committing to a main branch (one that won’t be squashed) it’s very helpful to prefix all, or at least most of the commit messages with some normalized set of verbs. The tense and casing is totally up to you but keeping them normalized makes it very easy to scan. I like to use “add”, “remove”, “update”, “refactor”, “fix”, and so on as shown here:

* bafaeac TJ Holowaychuk — add mixin property array support
* e9df63a TJ Holowaychuk — remove opacity plugin. Closes #29
* c5b1e85 TJ Holowaychuk — remove media macros. Closes #36
译者信息

译者信息

中奖啦
中奖啦
翻译于 3年前

1 此译文

这写都是我个人的约定,你可以取其精华或忽略它,但是你和你的团队最好要有一些某种形式上的约定!:)

尊重现有项目的约定

这种情况并不多见,但是当你往一个你可以直接访问的开源项目中提交代码或补丁时,你最好花几分钟的时间了解一下该项目以前的提交记录,并且了解一下该项目的作者是怎样组织文件的。

为提交信息添加动词前缀

当你往一个主分支(one that won't be squashed)提交代码时,你最好为所有的提交信息加上前缀,或者至少为绝大部分的提交信息加上标准化的动词前缀。何时添加以及添加的频率有你决定,但是最好使用标准化的动词,这可以更容易的快速浏览。我喜欢用"add", "remove", "update", "refector", "fix" 等,如下所示:

* bafaeac TJ Holowaychuk — add mixin property array support
* e9df63a TJ Holowaychuk — remove opacity plugin. Closes #29
* c5b1e85 TJ Holowaychuk — remove media macros. Closes #36

Updating Dependencies With a Note

When updating a dependency in your project you might be tempted to just commit “update foo”, but if there’s a specific reason you’re updating a dependency it can be really helpful to your collaborators (and your future self) to make note of why you bumped the dep.

Branch Names

Nothing too special here, I typically just use the same convention as commit messages for branches like “add/my-feature”, “remove/old-feature”, “fix/crazy-bug”.

Squashing Commits

In your own codebase and when contributing to other projects, it’s pretty important to keep a clean commit history, at least as clean as you can without driving yourself mad. One important aspect of this is “squashing” commits when appropriate, to form a single commit.

译者信息

译者信息

中奖啦
中奖啦
翻译于 3年前

1 此译文

更新依赖的时候做个记录

当你更新你项目中的某个依赖时,你也许仅仅只用"update foo"类似这样的信息来提交你的代码,但是如果是出于某些原因你需要更新依赖,你最好为你的提交信息做一个简单的记录,这会对该项目的其他开发者(或者以后的你)很有帮助。

分支名称

这里没有什么特殊的,我通常会使用提交信息中同样的约定来命名分支,像 “add/my-feature”, “remove/old-feature”, “fix/crazy-bug”。

合并提交

在你自己的代码库或当你向其他项目贡献代码时,你最好保持一个清晰的提交记录,至少也要足够清晰以免把你自己搞乱。其中一个重要的方面就是在适当的时候“合并(squashing)”提交记录来形成一个单个的提交记录。

This is a bit of a controversial topic since squashing several commits into one can make bisecting more difficult, but for small focused changes which you should be aiming for anyway this often increases clarity.

For example if someone was to send a pull-request to your project fixing a single bug, but the pull-request contains 3 commits as shown below. Chances are you don’t really care about the top and bottom two, really you just want a single commit with both the test and fix, making it easy to revert, easy to scan in your main branch, and equally easy to bisect as long as the changes are focused.

- fix typo
- fix something. Closes #123
- add test for fixing something

What you really want is:

- fix something. Closes #123

To do this you can use the git-squash(1) command in git-extras, although I’m sure one of the GIT gods out there could point to a built-in solution!

译者信息

译者信息

中奖啦
中奖啦
翻译于 3年前

1 此译文

这是一个有点争议的话题,因为将多个提交合并成一个会使得二分查找(bisecting)更见困难,但是对于一些小的修改,这往往会有助于提交记录的清晰。

举例来说,如过某个人向你的项目中发送了一个pull-request来修复一个bug,但是这个pull-request包含3个提交记录,如下所示。你很可能不会关心最上面和最下面的那两个提交记录,你可能只需要一个包括了test和fix在内的提交,这可以更容易的恢复(revert),更容易的在你的主分支中进行浏览,只要聚焦于这些修改,也同样容易进行二分查找(bisect)

- fix typo
- fix something. Closes #123
- add test for fixing something

你真正想要的是:

- fix something. Closes #123

你可以使用 git-extras 中的 git-squash(1) 命令来实现它,尽管我相信某一个GIT大神会给出一个内建(build-in)的解决方案。

EDIT: @defunctzombie suggested just using a simple reset —soft here and then re-commit the staged changed. The only difference then between this and git-squash(1) is that the latter will squash an entire branch (be careful!!).

EDIT 2: turns out there’s a git-merge —squash flag that effectively does what git-squash does, so there’s not much point in using that. Here’s the snippet from the manpage:

 —squash, —no-squash
 Produce the working tree and index state as if a real merge happened (except for the merge information), but do not
 actually make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to cause the next git commit command to
 create a merge commit. This allows you to create a single commit on top of the current branch whose effect is the
 same as merging another branch (or more in case of an octopus).

Ephemeral Branches

For short-lived branches that I’m confident about squashing I drop feature related prefixing. For example where two regular commits may be “fix facebook oauth integration”, and “add test for facebook oauth integration bug”, in a branch named fix/facebook-oauth I would typically just make commits like “add test”, “fix integration” so they still make sense but you’re not wasting a lot of time.

译者信息

译者信息

中奖啦
中奖啦
翻译于 3年前

1 此译文

EDIT: @defunctzombie 建议只需简单的使用 reset —soft,之后再重新提交修改即可。这种方法和git-squash(1)之间的唯一区别是后者会合并(squash)整个分支(要小心!!)。

EDIT 2: 最终发现git-merge 有一个--squash 选项可以有效的完成git-squash的工作,所以没有必要再多做介绍如何使用了。下面是它的用户手册的一个片段:

 —squash, —no-squash
 Produce the working tree and index state as if a real merge happened (except for the merge information), but do not
 actually make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to cause the next git commit command to
 create a merge commit. This allows you to create a single commit on top of the current branch whose effect is the
 same as merging another branch (or more in case of an octopus).

短暂的分支

对于一些我确定我会合并的短暂分支来说,在提交时,我会去掉功能相关的前缀。例如,在一个名为 fix/facebook-auth 的分支中有两个常规的提交“fix facebook oauth integration” 和 “add test for facebook oauth integration bug”, 我通常只会像这样提交,"add test",“fix integration”,这样它们依旧有意义,但是这可以为你节省很多时间。

Keep a Changelog

Most people do this but it’s definitely something I would consider very important, telling your user-base to “just read the commit log” is not fun and no one wants to do that. When you issue a release people just want the gist of changes, ordered neatly so they can see what has been added, fixed, removed, etc.

I use git-changelog(1) in git extras to generate the changelog, however if you were strict about conventions you could use something more strict that doesn’t require any manual massaging like git-changelog(1) does.

译者信息

译者信息

petert
petert
翻译于 3年前

1 此译文

留下一份记录

大部分人都会这么做但我还想强调一下,告诉使用者去“查看提交日志”是不友好的. 当你提交一个版本后,大家只想看到更改部分的日志, 或是排序后的日志,可以方便的看到那些是添加的,修改的,删除的等等.

我用的是 git-change log(1) 来生成更改日志, 如果你还需要更严格的日志记录,那也许不需要像git-change log(1) 那样的处理.

Closing and Referencing Tickets

I think most GitHub-ers know this and take advantage of it but it’s worth mentioning. When you commit with a string like “Closes #123" GitHub sees this and will actually close the issue for you, along with referencing the commit in the issue.

The same goes for referencing, just place “#123" in the commit message or body to thread things along, this is a small but awesome feature of GitHub that you should definitely consider taking advantage of.

译者信息

译者信息

petert
petert
翻译于 3年前

1 此译文

关闭和引用

我想大部分 GitHub-ers都知道这个功能,但我还要再强调一下. 如果提交了 “Closes #123" 字样的字符串,Github就会关闭这个条目,并创建该条目的注释引用.

引用的时候也一样, 在注释中写上 “#123" 以分类标识, 这是Github一个不起眼却很强大的功能,最好能合理应用.

Tagging Commits

This isn’t something I do often myself, but I’d like to get started tagging my commits more often. For example when you produce a changelog you often still need to weed out these “real” changes, because no one has a perfect commit log — but if you were to tag relevant changes with #change or [change], then this would be trivial.

Some people also use feature or aspect related tags like #ui, #ux and similar, I think these could be pretty helpful from a stats point of view but also adds clarity to changes.

译者信息

译者信息

petert
petert
翻译于 3年前

1 此译文

提交的标签

我是不太使用这条功能,但我会积极尝试. 比如生成了更新日之后还是需要分出哪些是“真正的” 更新, 谁也没法确保提交日志的准确 — 但如果在相应的提交记录里添加#change或是[change]标签, 区分起来就很容易了.

其他人也会使用#ui, #ux 或其他类似标签来标识, 我想不管从统计的角度或是易读性方面都很好.

One thing we did at Cloudup is prefix all commits with the module’s name. This is a nice side-effect of having a truly modular application, it’s a lot harder for people to step on each other’s feet. For example instead of “add gravatar support to signup”, we would use “signup: add gravatar support”, making things even more obvious for someone scanning the log.

Any Suggestions?

Those are my main suggestions but I’d love to hear others as well if you find a particular convention you use is critical to your work flow.

译者信息

译者信息

petert
petert
翻译于 3年前

1 此译文

我们在 Cloudup的提交都加上了相关模块名字的前缀. 这样确实是模块化的开发,但却影响了后续的代码提交. 比如 “add gravatar support to signup”, 可以这么写“signup: add gravatar support”, 这样能让人们更容易识别.

还有其他好的建议?

以上都是我的一些使用心得,如果在你的工作中发现了其他更有效的使用方法,请不吝赐教.

顶部