Một mục hướng lập trình viên trong kho dữ liệu GitHub của TopGit: agis/git-style-guide, 5.1k sao, nhóm Developer Tools. A Git Style Guide
Tóm tắt dựng từ metadata GitHub của chính dự án — chưa có bài review TopGit. Trang sẽ tự động cập nhật khi bài review đầy đủ được xuất bản.
VÌ SAO CHƯA CÓ REVIEW
TopGit viết bài đầy đủ cho repo có nhiều sao nhất và được yêu cầu nhiều nhất. Trang này là snapshot trong thời gian chờ — xem README gốc ở tab READ ME.
This is a Git Style Guide inspired by How to Get Your Change Into the Linux
Kernel,
the git man pages and various practices popular
among the community.
Translations are available in the following languages:
Chinese (Simplified)
Chinese (Traditional)
French
Georgian
German
Greek
Italian
Japanese
Korean
Polish
Portuguese
Russian
Spanish
Thai
Turkish
Ukrainian
If you feel like contributing, please do so! Fork the project and open a pull
request.
Table of contents
Branches
Commits
Messages
Merging
Misc.
Branches
Choose short and descriptive names:
# good
$ git checkout -b oauth-migration
# bad - too vague
$ git checkout -b login_fix
Identifiers from corresponding tickets in an external service (eg. a GitHub
issue) are also good candidates for use in branch names. For example:
# GitHub issue #15
$ git checkout -b issue-15
Use lowercase in branch names. External ticket identifiers with uppercase
letters are a valid exception. Use hyphens to separate words.
$ git checkout -b new-feature # good
$ git checkout -b T321-new-feature # good (Phabricator task id)
$ git checkout -b New_Feature # bad
When several people are working on the same feature, it might be convenient
to have personal feature branches and a team-wide feature branch.
Use the following naming convention:
Merge at will the personal branches to the team-wide branch (see "Merging").
Eventually, the team-wide branch will be merged to "main".
Delete your branch from the upstream repository after it's merged, unless
there is a specific reason not to.
Tip: Use the following command while being on "main", to list merged
branches:
$ git branch --merged | grep -v "\*"
Commits
Each commit should be a single logical change. Don't make several
logical changes in one commit. For example, if a patch fixes a bug and
optimizes the performance of a feature, split it into two separate commits.
Tip: Use git add -p to interactively stage specific portions of the
modified files.
Don't split a single logical change into several commits. For example,
the implementation of a feature and the corresponding tests should be in the
same commit.
Commit early and often. Small, self-contained commits are easier to
understand and revert when something goes wrong.
Commits should be ordered logically. For example, if commit X depends
on changes done in commit Y, then commit Y should come before commit X.
Note: While working alone on a local branch that has not yet been pushed, it's
fine to use commits as temporary snapshots of your work. However, it still
holds true that you should apply all of the above before pushing it.
Messages
Use the editor, not the terminal, when writing a commit message:
# good
$ git commit
# bad
$ git commit -m "Quick fix"
Committing from the terminal encourages a mindset of having to fit everything
in a single line which usually results in non-informative, ambiguous commit
messages.
The summary line (ie. the first line of the message) should be
descriptive yet succinct. Ideally, it should be no longer than
50 characters. It should be capitalized and written in imperative present
tense. It should not end with a period since it is effectively the commit
title:
# good - imperative present tense, capitalized, fewer than 50 characters
Mark huge records as obsolete when clearing hinting faults
# bad
fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.
After that should come a blank line followed by a more thorough
description. It should be wrapped to 72 characters and explain why
the change is needed, how it addresses the issue and what side-effects
it might have.
It should also provide any pointers to related resources (eg. link to the
corresponding issue in a bug tracker):
Short (50 chars or fewer) summary of changes
More detailed explanatory text, if necessary. Wrap it to
72 characters. In some contexts, the first
line is treated as the subject of an email and the rest of
the text as the body. The blank line separating the
summary from the body is critical (unless you omit the body
entirely); tools like rebase can get confused if you run
the two together.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Use a hyphen or an asterisk for the bullet,
followed by a single space, with blank lines in
between
The pointers to your related resources can serve as a footer
for your commit message. Here is an example that is referencing
issues in a bug tracker:
Resolves: #56, #78
See also: #12, #34
Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Ultimately, when writing a commit message, think about what you would need
to know if you run across the commit in a year from now.
If a commit A depends on commit B, the dependency should be
stated in the message of commit A. Use the SHA1 when referring to
commits.
Similarly, if commit A solves a bug introduced by commit B, it should
also be stated in the message of commit A.
If a commit is going to be squashed to another commit use the --squash and
--fixup flags respectively, in order to make the intention clear:
$ git commit --squash f387cab2
(Tip: Use the --autosquash flag when rebasing. The marked commits will be
squashed automatically.)
Merging
Do not rewrite published history. The repository's history is valuable in
its own right and it is very important to be able to tell what actually
happened. Altering published history is a common source of problems for
anyone working on the project.
However, there are cases where rewriting history is legitimate. These are
when:
You are the only one working on the branch and it is not being reviewed.
You want to tidy up your branch (eg. squash commits) and/or rebase it onto
the "main" in order to merge it later.
That said, never rewrite the history of the "main" branch or any other
special branches (ie. used by production or CI servers).
Keep the history clean and simple. Just before you merge your branch:
Make sure it conforms to the style guide and perform any needed actions
if it doesn't (squash/reorder commits, reword messages etc.)
Rebase it onto the branch it's going to be merged to:
[my-branch] $ git fetch
[my-branch] $ git rebase origin/main
# then merge
This results in a branch that can be applied directly to the end of the
"main" branch and results in a very simple history.
(Note: This strategy is better suited for projects with short-running
branches. Otherwise it might be better to occassionally merge the
"main" branch instead of rebasing onto it.)
If your branch includes more than one commit, do not merge with a
fast-forward:
# good - ensures that a merge commit is created
$ git merge --no-ff my-branch
# bad
$ git merge my-branch
Misc.
There are various workflows and each one has its strengths and weaknesses.
Whether a workflow fits your case, depends on the team, the project and your
development procedures.
That said, it is important to actually choose a workflow and stick with it.
Be consistent. This is related to the workflow but also expands to things
like commit messages, branch names and tags. Having a consistent style
throughout the repository makes it easy to understand what is going on by
looking at the log, a commit message etc.
Test before you push. Do not push half-done work.
Use annotated tags
for marking releases or other important points in the history. Prefer
lightweight tags
for personal use, such as to bookmark commits for future reference.
Keep your repositories at a good shape by performing maintenance tasks
occasionally:
git-gc(1)
git-prune(1)
git-fsck(1)
License
This work is licensed under a Creative Commons Attribution 4.0
International license.
Credits
Agis Anastasopoulos / @agisanast / http://agis.io
... and contributors!
Có — agis/git-style-guide phát hành theo license CC-BY-4.0, nghĩa là mã nguồn mở để đọc, fork và (tùy license) tái sử dụng. Mã: github.com/agis/git-style-guide.
agis/git-style-guide là gì?
agis/git-style-guide (agis/git-style-guide) là dự án đa ngôn ngữ trên GitHub. Theo mô tả gốc: A Git Style Guide
agis/git-style-guide so với các dự án Developer Tools khác thế nào?
agis/git-style-guide được TopGit xếp vào nhóm Developer Tools, với 5.1k sao GitHub. Xem trang chủ đề Developer Tools trên TopGit để so sánh với các dự án tương tự theo số sao và mức độ hoạt động.
Cùng nhóm Developer Tools còn repo nào?
agis/git-style-guide thuộc nhóm Developer Tools trên TopGit, cùng 4 topic GitHub. Trang Trending và Topics liệt kê các repo cùng số sao và cùng ngôn ngữ để so sánh.
Đọc thêm về agis/git-style-guide ở đâu?
Trang TopGit này là một snapshot — tab "Readme" hiển thị nguyên văn README của repo (đã bỏ link, giữ ảnh). Repo GitHub ở github.com/agis/git-style-guide là nguồn chính thức.
Vì sao agis/git-style-guide được xếp vào nhóm Developer Tools?
TopGit xếp agis/git-style-guide vào nhóm Developer Tools dựa trên GitHub topics và mô tả của repo (gắn thẻ: "git", "style", "style-guide"). Việc phân loại dựa trên metadata thật của repo, không phải đoán theo cảm tính biên tập.
Đọc đầy đủ README ở tab phía trên.
Chưa chắc git-style-guide có hợp với bạn?
Để ChatGPT, Claude hoặc Perplexity tìm hiểu giúp — bấm bên dưới và xem AI nói gì về git-style-guide.