Showing preview only (293K chars total). Download the full file or copy to clipboard to get everything.
Repository: RomuloOliveira/commit-messages-guide
Branch: master
Commit: aa781692b451
Files: 21
Total size: 283.3 KB
Directory structure:
gitextract_c26l5f1i/
├── CODEOWNERS
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README_az-AZ.MD
├── README_de-DE.md
├── README_es-AR.md
├── README_fa-IR.md
├── README_fr-FR.md
├── README_gr-GR.md
├── README_it-IT.md
├── README_ja-JP.md
├── README_ko-KR.md
├── README_pl-PL.md
├── README_pt-BR.md
├── README_ru-RU.md
├── README_tr-TR.md
├── README_ua-UA.md
├── README_vi-VN.md
├── README_zh-CN.md
└── README_zh-TW.md
================================================
FILE CONTENTS
================================================
================================================
FILE: CODEOWNERS
================================================
* @RomuloOliveira
README_de-DE.md @Ana06
README_ua-UA.md @CODER591
================================================
FILE: CONTRIBUTING.md
================================================
# Contributing
First of all, thanks for the taking time to contribute and help people!
This document contains a set of guidelines for contributing to the repository. These guidelines are intended to provide a clear and concise to help you to know where help is needed and how you can contribute to improve the guide.
## Where can I help?
There are several ways to contribute. A contribution could happen both in the form of changes to the repository itself or through pull request reviews. Any kind of help would be appreciated.
In special, I'd like to highlight and bring attention to help in the form of:
- Fix of inconsistencies across languages
- Grammar and spelling corrections
- Improvement of source referencing (images, references, etc.)
- Incorrect, inconsistent or incomplete information fixes
- Pull request reviews
- Translation to other languages
## Principles
- **Consistency across languages over 100% correct grammar/spelling**: It's better to have some grammar and spelling errors than having outdated or specialized content for a single language. Use Google Translate or similar tools when needed.
- **Best practices in this guide should aim to help, not to set rule-following blindly standards**: It's intended to provide resourceful guidelines to help people communicate in a better, concise and clear way. It's a mean to an end, not the end itself.
- **One size does not fit all**: A project, team or company standards and agreements may override common practices. People may not agree 100% with all practices and it's ok. These things should not led to add or remove a guideline. Helping people should.
- **Native speakers are owners, but two heads are better than one**: Pull request authors do the best they can, but this doesn't replaces a good review by another native speaker.
Feel free to propose improvements if you have.
## Guidelines
Try to follow these guidelines when contributing. They're not rules and I'll not strictly enforce them, although I may ask you to adapt your contribution according to it.
Feel free to propose changes to the guidelines and use your best judgment.
### General guidelines
- You may fork the project to make changes to the repository. See [this Github guide](https://guides.github.com/activities/forking/) explaining how to do it.
- Use English for commit messages, issues and pull requests (both description and discussions).
- Use the [best practices](https://github.com/RomuloOliveira/commit-messages-guide#good-practices) described in the guide.
- Add `[PROPOSAL]` prefix to PR title when doing additions other than translations or corrections (e.g., [#31](https://github.com/RomuloOliveira/commit-messages-guide/pull/31))
- Github editor usually suggests a commit message like "Update file", add a description of your change in the commit body or change the title.
- A good example: [7747659](https://github.com/RomuloOliveira/commit-messages-guide/commit/7747659824b83f6d07589daa66a67ee29fa60ddb)
It worth noting again that the best practices described in this guide are _guidelines_ and not rules. I won't refuse your contribution nor nitpick your commit messages if you're not following them strictly. It aims to help.
### New translation checklist
- Make sure you're working in the most updated branch. Rebase your code and fix conflicts when needed.
- Make sure you've updated the [Available languages section](https://github.com/RomuloOliveira/commit-messages-guide#available-languages) section in (and only in) README.md.
- Make sure you haven't included `Available languages` section in your translation (See [#31](https://github.com/RomuloOliveira/commit-messages-guide/pull/31)).
### Pull Request review process
Preferably, there should be at least 1 review from a native speaker. All pull requests will stay open for a few days waiting for a review help. Translations that didn't had a thorough review by a native speakers should be merged in a couple days, though.
All discussions should be resolved before a merge. Only [code owners](https://github.com/RomuloOliveira/commit-messages-guide/blob/master/CODEOWNERS) can do a merge. Native speakers have the authority to request changes in any pull request.
Everything that applies to a native speaker also applies to a fluent writer.
## Author notes
_by @RomuloOliveira_
I'm a Brazilian Portuguese native speaker still working on my English. I'll try to review all translations using Google Translate but a native speaker review is way more valuable.
I'll open pull requests for significant changes and proposals, but I may commit directly to the master branch for minor fixes or changes that do not affect translations' content.
Opinions and contents are my own and don't necessarily represent those of my current or former employers.
## Thanks
Helping people is priceless and I thank every and each of you that contributed to this guide.
================================================
FILE: LICENSE
================================================
Attribution 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More_considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution 4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution 4.0 International Public License ("Public License"). To the
extent this Public License may be interpreted as a contract, You are
granted the Licensed Rights in consideration of Your acceptance of
these terms and conditions, and the Licensor grants You such rights in
consideration of benefits the Licensor receives from making the
Licensed Material available under these terms and conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
d. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
e. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
f. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
g. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
h. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
i. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
j. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
k. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
4. If You Share Adapted Material You produce, the Adapter's
License You apply must not prevent recipients of the Adapted
Material from complying with this Public License.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material; and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
================================================
FILE: README.md
================================================
# Commit messages guide
[](https://saythanks.io/to/RomuloOliveira)
A guide to understanding the importance of commit messages and how to write them well.
It may help you to learn what a commit is, why it is important to write good messages, best practices and some tips to plan and (re)write a good commit history.
## Available languages
- [English](README.md)
- [Português](README_pt-BR.md)
- [Deutsch](README_de-DE.md)
- [Español](README_es-AR.md)
- [Italiano](README_it-IT.md)
- [한국어](README_ko-KR.md)
- [Русский](README_ru-RU.md)
- [简体中文](README_zh-CN.md)
- [日本語](README_ja-JP.md)
- [Українська](README_ua-UA.md)
- [Türkçe](README_tr-TR.md)
- [ngôn ngữ tiếng Việt](README_vi-VN.md)
- [繁體中文](README_zh-TW.md)
- [ελληνικά](README_gr-GR.md)
- [Française](README_fr-FR.md)
- [پارسی](README_fa-IR.md)
- [Polish](README_pl-PL.md)
- [Azərbaycanca](README_az-AZ.md)
## What is a "commit"?
In simple terms, a commit is a _snapshot_ of your local files, written in your local repository.
Contrary to what some people think, [git doesn't store only the difference between the files, it stores a full version of all files](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
For files that didn't change from one commit to another, git stores just a link to the previous identical file that is already stored.
The image below shows how git stores data over time, in which each "Version" is a commit:
## Why are commit messages important?
- To speed up and streamline code reviews
- To help in the understanding of a change
- To explain "the whys" that cannot be described only with code
- To help future maintainers figure out why and how changes were made, making troubleshooting and debugging easier
To maximize those outcomes, we can use some good practices and standards described in the next section.
## Good practices
These are some practices collected from my experiences, internet articles, and other guides. If you have others (or disagree with some) feel free to open a Pull Request and contribute.
### Use imperative form
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
_But why use the imperative form?_
A commit message describes what the referenced change actually **does**, its effects, not what was done.
### Capitalize the first letter
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
The reason that the first letter should be capitalized is to follow the grammar rule of using capital letters at the beginning of sentences.
The use of this practice may vary from person to person, team to team, or even from language to language.
Capitalized or not, an important point is to stick to a single standard and follow it.
### Try to communicate what the change does without having to look at the source code
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
It is useful in many scenarios (e.g. multiple commits, several changes and refactors) to help reviewers understand what the committer was thinking.
### Use the message body to explain "why", "for what", "how" and additional details
Focus on the "why" instead of "what" (although "what" and "how" are still important).
If, for example, your commit message is a restatement of the diff, it may be important to
rethink it.
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
The subject and the body of the messages are separated by a blank line.
Additional blank lines are considered as a part of the message body.
Characters like `-`, `*` and \` are elements that improve readability.
### Avoid generic messages or messages without any context
```
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### Avoid language such as "this PR", "this commit", "this patch"
You don't have to refer to the commit by itself. We **know** that this is a patch, commit or PR.
```
# Bad
This commit does x and y...
This PR does x and y...
This Patch x and y...
# Good
X and y are done...
```
### Avoid personal language (e.g. pronouns)
A thing that can be learned from academic writing and brought to commit messages is to avoid using personal
language.
```
# Bad
I fixed the problem.
# Good
The problem has been fixed by doing x and y...
```
### Limit the number of characters
[It's recommended](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) to use a maximum of 50 characters for the subject and 72 for the body.
### Keep language consistency
For project owners: Choose a language and write all commit messages using that language. Ideally, it should match the code comments, default translation locale (for localized projects), etc.
For contributors: Write your commit messages using the same language as the existing commit history.
```
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Good (Portuguese example)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Template
This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## Notes on PR messages and cover letters
Most developers open Pull Requests (PR) on a Git repo through a platform (Github, Gitlab),
while kernel developers and people who send patches through email ([yes, that's a
thing](https://git-scm.com/docs/git-send-email/2.45.0) refer to it as "cover letter".
A good cover letter, or PR message, will summarize, give background and context to a series of
commits that are related. Good writing on this part will help to "sell" your commit series to
the maintainers of a project, as they'll be able to understand why you are presenting such changes
together.
If you're writing a smaller (single or a few commits) change, treat the first commit as a cover letter.
Github, for example, uses this first commit as the default PR message.
Here's an [example](https://lore.kernel.org/lkml/20230414225551.858160935@linutronix.de/) of a good cover
letter sent on the Linux kernel mailing list. It contains:
- A description of the overall changes and why they were made;
- Background, or any important information that is needed to understand these changes;
- A breakdown of the solution and the approach taken to reach such solution;
- Caveats, or things that could go wrong and must be considered before applying such changes;
- Possible enhancements, a section describing opportunities for future changes that are out of the scope
for the current commit set;
## Signing off your commits and following guidelines
Open source projects often require you to sign your code and follow some guidelines. One such example is
the Developer Certificate of Origin (DCO)[https://developercertificate.org/], which you have to abide to
when contributing to projects by The Linux Foundation, the Cloud Native Computing Foundation and many
others.
This means that you have to use your **real name** (i.e. a name that identifies you, _not necessarily your
legal name_) and to sign off your commits. Avoid pseudonyms or false names. Further reading about real names
[here](https://www.mail-archive.com/kernelnewbies@kernelnewbies.org/msg22178.html).
Use `git config` to set your name and email.
``` sh
# You can apply these changes locally, to a single repo
git config --local user.name "Jane Doe"
git config --local user.email "janedoe@janedoe.com"
# Or globally
git config --global user.name "Jane Doe"
git config --global user.email "janedoe@janedoe.com"
```
When doing a commit, add the `-s` flag to `git commit` and that will add a `Signed-off-by: ` line to your
commit.
Aside from adding this line to the commit, it's also important to use GPG for signing your commits.
GPG, or GNU Privacy Guard, is a tool that allows you to encrypt and tamperproof documents. You can use it,
for example, to sign emails and ensure that they haven't been modified without your consent. In the git
world, this is how you tell that a commit has been made by you and has not been tampered before reaching
other people.
Github has more [information](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account)
about how to generate and add a GPG key to your account. [This documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)
teaches how to use gpgsign for commits.
More information about working with GPG [here](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work).
For even more security, you can setup [pinentry](https://www.gnupg.org/related_software/pinentry/index.html)
to add physical layers of security to GPG, such as signing your commits with Yubikey of Touch ID.
## Rebase vs. Merge
This section is a **TL;DR** of Atlassian's excellent tutorial, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** Applies your branch commits, one by one, upon the base branch, generating a new tree.
### Merge
**TL;DR:** Creates a new commit, called (appropriately) a _merge commit_, with the differences between the two branches.
### Why do some people prefer to rebase over merge?
I particularly prefer to rebase over merge. The reasons include:
- It generates a "clean" history, without unnecessary merge commits
- _What you see is what you get_, i.e., in a code review all changes come from a specific and entitled commit, avoiding changes hidden in merge commits
- More merges are resolved by the committer, and every merge change is in a commit with a proper message
- It's unusual to dig in and review merge commits, so avoiding them ensures all changes have a commit where they belong
### When to squash
"Squashing" is the process of taking a series of commits and condensing them into a single commit.
It's useful in several situations, e.g.:
- Reducing commits with little or no context (typo corrections, formatting, forgotten stuff)
- Joining separate changes that make more sense when applied together
- Rewriting _work in progress_ commits
### When to avoid rebase or squash?
Avoid rebase and squash in public commits or in shared branches where multiple people work on.
Rebase and squash rewrite history and overwrite existing commits, doing it on commits that are on shared branches (i.e., commits pushed to a remote repository or that comes from others branches) can cause confusion and people may lose their changes (both locally and remotely) because of divergent trees and conflicts.
## Useful git commands
### rebase -i
Use it to squash commits, edit messages, rewrite/delete/reorder commits, etc.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Use it to clean up commits easily and without needing a more complex rebase.
[This article](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) has very good examples of how and when to do it.
### cherry-pick
It is very useful to apply that commit you made on the wrong branch, without the need to code it again.
Example:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Let's say we have the following diff:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
We can use `git add -p` to add only the patches we want to, without the need to change the code that is already written.
It's useful to split a big change into smaller commits or to reset/checkout specific changes.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Other interesting stuff
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Like it?
[Say thanks!](https://saythanks.io/to/RomuloOliveira)
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
- Grammar and spelling corrections
- Translation to other languages
- Improvement of source referencing
- Incorrect or incomplete information
## Inspirations, sources and further reading
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
- [Philosophy of Linux kernel patches](https://kernelnewbies.org/PatchPhilosophy)
- [The perfect patch](https://www.ozlabs.org/~akpm/stuff/tpp.txt)
================================================
FILE: README_az-AZ.MD
================================================
# Commit mesajları təlimatı
[](https://saythanks.io/to/RomuloOliveira)
Bu təlimat commit mesajlarının əhəmiyyətini və onların daha yaxşı necə yazılacağını izah edir.
Bu, "commit"-in nə olduğunu, yaxşı commit mesajları yazmağın nə üçün vacib olduğunu, yaxşı commit tarixçəsini planlaşdırmaq və (yenidən) yazmaq üçün bəzi nümunələr və məsləhətləri anlamağa kömək edə bilər.
## "commit" nədir?
Sadə dillə desək, commit sizin yerli reponuza yazılmış fayllarınızın *anlıq* görüntüsüdür.
Bəzi insanların düşündüyündən fərqli olaraq, [git yalnız fayllar arasındakı fərqləri saxlamır, bütün faylların tam versiyasını saxlayır](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
İki commit arasında dəyişməmiş fayllar üçün git, sadəcə olaraq, artıq saxlanmış əvvəlki eyni fayla keçid yaradacaq.
Aşağıdakı şəkil, git-in hər bir "versiya"ya uyğun olaraq məlumatları necə saxladığını göstərir:
## Commit mesajları niyə vacibdir?
- Kod baxışını (code review) daha sürətli və asan edir
- Dəyişikliyi anlamağa kömək edir
- Təkcə kodla izah edilə bilməyən "niyə"ni izah edir
- Sonrakı tərtibatçılara dəyişikliklərin niyə və necə edildiyini anlamağa kömək edir, problemlərin aradan qaldırılmasını və xətaların düzəldilməsini asanlaşdırır.
Bu faydaları maksimum dərəcədə artırmaq üçün biz növbəti bölmədə təsvir olunan bəzi ən yaxşı təcrübə və standartlardan istifadə edə bilərik.
## Ən yaxşı təcrübələr
Bunlar təcrübələrimdən, internetdəki məqalələrdən və digər təlimatlardan topladığım bəzi təcrübələrdir. Əlavə etmək istədiyiniz bir şey varsa (və ya razı deyilsinizsə), Pull Request açın və töhfə verin.
### Əmr formasından istifadə edin
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
_Bəs nə üçün əmr forması?_
Commit mesajı göstərilən dəyişiklikdə nə edildiyini deyil, əslində, nə etdiyini və onun təsirlərini təsvir edir.
### Böyük hərf ilə başlayın
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
Böyük hərflə başlamağın səbəbi, qrammatik qaydalardan biri olan cümlələrin əvvəlində böyük hərflərdən istifadəyə riayət etməkdir.
Bunun istifadəsi insandan insana, komandadan komandaya və hətta dildən dilə dəyişə bilər. Böyük hərflə yazın və ya yazmayın, əsas məsələ bir standarta bağlı qalmaq və ona əməl etməkdir.
### Mənbə koduna baxmadan dəyişikliyin nə etdiyini bildirməyə çalışın
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
Bu təcrübə bir çox ssenarilərdə (məsələn, çoxlu commitlər, çoxsaylı dəyişikliklər və refaktorinqlər zamanı) mesaj oxuyanlara xəbər verənin nə düşündüyünü anlamağa kömək etmək üçün faydalıdır.
### "Niyə?", "Nə məqsədlə?", "Necə?" suallarını və əlavə detalları izah etmək üçün mesaj mətnindən istifadə edin
“Nə” əvəzinə “niyə”yə diqqət yetirin (baxmayaraq ki, “nə” və “necə” hələ də vacibdir).
Məsələn, commit mesajınız diff-in yenidən ifadəsidirsə, onu yenidən nəzərdən keçirmək vacib ola bilər.
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
Mesajların mövzusu və mətni boş sətirlə ayrılır.
Əlavə boş sətirlər mesajın əsas hissəsi hesab olunur.
`-`, `*` və \` kimi simvollar oxunaqlılığı artıran elementlərdir.
### Ümumi və ya hərhansı konteksti olmayan mesajlardan çəkinin
```
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### "this PR", "this commit", "this patch" kimi yazı dilindən çəkinin
Bir commitin özünə müraciət etmək lazım deyil. Biz **bilirik** ki, bu, yol, commit və ya PR-dır.
```
# Bad
This commit does x and y...
This PR does x and y...
This Patch x and y...
# Good
X and y are done...
```
### Şəxsi dildən çəkinin (məsələn, əvəzliklər)
Akademik yazılardan öyrənib, mesajların göndərilməsinə də tətbiq edə biləcəyimiz bir şey, şəxsi dildən istifadə etməməkdir.
```
# Bad
I fixed the problem.
# Good
The problem has been fixed by doing x and y...
```
### Simvolların sayını məhdudlaşdırın
Mövzu üçün 50 simvoldan, mətn üçün isə 72 simvoldan çox olmamaq [tövsiyə olunur](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines).
### Dil ardıcıllığını qoruyun
Layihə sahibləri üçün: Bir dil seçin və bütün commit mesajlarını həmin dildə yazın. İdeal olaraq, kod şərhləri, standart yerli tərcümə parametrləri (lokallaşdırılmış layihələr üçün) və s. ilə uyğun gəlməlidir.
Töhfə verənlər üçün: Mövcud commit tarixçəsi ilə eyni dildən istifadə edərək commit mesajı yazın.
```
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Good (Portuqalca nümunə)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Bad (İngiliscə və Portuqalca qarışıq)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Şablon
Bu şablonun orijinalı [Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) tərəfindən yazılıb: [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## PR mesajları və müşayiət məktubları haqqında qeydlər
Əksər tərtibatçılar Git reposunda Pull Request (PR) yaratmaq üçün bir platformadan (GitHub, GitLab) istifadə edirlər, lakin nüvə (kernel) tərtibatçıları və dəyişiklikləri e-poçt vasitəsilə göndərən şəxslər ([bəli, belə bir şey var](https://git-scm.com/docs/git-send-email/2.45.0) ) bunu "cover letter" (müşayiət məktubu) adlandırırlar.
Yaxşı bir müşayiət məktubu və ya PR mesajı bir-biri ilə əlaqəli olan commit seriyasını ümumiləşdirir, onların mənşəyi və konteksti haqqında məlumat verir. Bu hissənin yaxşı yazılması commit seriyanızı layihənin saxlayıcılarına "satmağa" kömək edəcək, çünki onlar təqdim etdiyiniz dəyişikliklərin niyə birlikdə göndərildiyini asanlıqla anlaya biləcəklər.
Əgər daha kiçik (bir və ya bir neçə commit-lik) dəyişiklik edirsinizsə, ilk commit-i müşayiət məktubu kimi qəbul edin. Məsələn, GitHub ilk commit-i standart PR mesajı kimi istifadə edir.
Linux nüvəsi (kernel) e-poçt siyahısına göndərilmiş yaxşı bir müşayiət məktubunun [nümunəsi budur](https://lore.kernel.org/lkml/20230414225551.858160935@linutronix.de/). O, aşağıdakıları ehtiva edir:
- Ümumi dəyişikliklərin təsviri və onların hansı səbəblə edildiyi;
- Bu dəyişiklikləri anlamaq üçün vacib olan arxa plan və digər mühüm məlumatlar;
- Həllin detallı izahı və bu həllə çatmaq üçün tətbiq edilən yanaşma;
- Çətinliklər və ya tətbiq etməzdən əvvəl nəzərə alınmalı potensial problemlər;
- Mümkün təkmilləşdirmələr – cari commit dəstinin əhatə dairəsindən kənarda qalan gələcək dəyişikliklər üçün imkanları təsvir edən bölmə.
## Commit-ləri imzalamaq və qaydalara riayət etmək
Açıq mənbə (open-source) layihələr tez-tez kodunuzu imzalamağı və müəyyən qaydalara əməl etməyi tələb edir. Bunun bir nümunəsi **Developer Certificate of Origin (DCO)**-dur ([DCO saytı](https://developercertificate.org/)), hansı ki, **The Linux Foundation**, **Cloud Native Computing Foundation** və digər təşkilatların layihələrinə töhfə verərkən riayət etməli olduğunuz bir qaydadır.
Bu o deməkdir ki, siz **həqiqi adınızdan** istifadə etməlisiniz (yəni, sizi müəyyən edən bir ad, _mütləq hüquqi adınız olmalı deyil_) və commit-lərinizi imzalamalısınız. Təxəllüslərdən və ya saxta adlardan istifadə etməyin. **Həqiqi adlardan istifadə haqqında daha ətraflı** [buradan oxuya bilərsiniz](https://www.mail-archive.com/kernelnewbies@kernelnewbies.org/msg22178.html).
Adınızı və e-poçtunuzu təyin etmək üçün aşağıdakı `git config` əmrlərindən istifadə edin:
``` sh
# Bu dəyişiklikləri yerli olaraq tək repoya tətbiq edə bilərsiniz
git config --local user.name "Jane Doe"
git config --local user.email "janedoe@janedoe.com"
# Və ya qlobal olaraq
git config --global user.name "Jane Doe"
git config --global user.email "janedoe@janedoe.com"
```
Commit edərkən `git commit` əmrinə `-s` bayrağını əlavə edin. Bu, commit-inizə **"Signed-off-by: "** sətrini əlavə edəcək.
Bu sətrin commit-ə əlavə olunmasından başqa, commit-lərinizi imzalamaq üçün **GPG (GNU Privacy Guard)** istifadə etmək də vacibdir.
GPG (və ya GNU Privacy Guard) sənədləri şifrələməyə və onların dəyişdirilməsinin qarşısını almağa imkan verən bir alətdir. Məsələn, e-poçtları imzalamaq və onların sizin razılığınız olmadan dəyişdirilmədiyini təmin etmək üçün istifadə edilə bilər. **Git dünyasında isə GPG commit-in həqiqətən sizin tərəfinizdən edildiyini və başqaları tərəfindən dəyişdirilmədiyini təsdiqləmək üçün istifadə olunur.**
GitHub-da **GPG açarını yaratmaq və hesabınıza əlavə etmək** haqqında daha ətraflı [məlumat](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) əldə edə bilərsiniz. **Commit-lər üçün gpgsign istifadəsi** ilə bağlı təlimatı [buradan](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) oxuya bilərsiniz.
**GPG ilə işləmək haqqında daha çox məlumatı** [buradan](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) əldə edə bilərsiniz.
Daha yüksək təhlükəsizlik üçün [pinentry](https://www.gnupg.org/related_software/pinentry/index.html) konfiqurasiya edə bilərsiniz. Bu, GPG üçün fiziki təhlükəsizlik qatlarını əlavə etməyə, məsələn, commit-lərinizi **Yubikey və ya Touch ID** ilə imzalamağa imkan verir.
## Rebase (yenidən baza) və Merge (birləşmə)
Bu hissə, Atlassian-ın ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) adlı möhtəşəm dərsliyinin TL;DR (Too long; didn't read/çox uzun idi; oxumadım) xülasəsidir.
### Rebase
**TL;DR:** Bu, branch commitlərini əsas branch-dan sonra yeni ağac yaratmaq üçün bir-bir tətbiq edir.
### Merge
**TL;DR:** İki branch arasındakı fərqləri ehtiva edən _merge commit_ adlı yeni commit yaradır.
### Niyə bəzi insanlar merge (birləşmə) əvəzinə rebase-ə (yenidən baza) üstünlük verirlər?
Şəxsən mən merge yerinə rebase-ə üstünlük verirəm. Səbəblər aşağıdakılardır:
* Gereksiz bir _merge commit_'i olmadan "temiz" bir geçmiş oluşturur.
* _Gördüğünüz şey, elde ettiğiniz şeydir_, yani bir kod incelemesinde, merge commit'inin ardında gizlenen değişikliklerden kaçınarak, tüm değişiklikler belirli ve başlıklı bir commit'ten gelir.
* Daha fazla merge, commit eden tarafından çözümlenir ve her bir merge işlemi uygun bir mesajla bir commit içindedir.
* Bir birleştirme commit'ini detaylı incelemek ve gözden geçirmek olağandışı bir durumdur, bu nedenle bunlardan kaçınmak tüm değişikliklerin ait oldukları bir commit'e sahip olmasını garanti eder.
- Lazımsız bir _merge commit_'i olmadan "təmiz" bir tarix yaradır.
- _Gördüyün şey, əldə etdiyin şeydir_, yəni kod icmalında merge commit-inin arxasında gizlənmiş dəyişikliklərdən qaçaraq, bütün dəyişikliklər müəyyən və başlıqlı bir commit-dən gəlir.
- Daha çox merge commit edən tərəfindən həll edilir və hər bir merge əməliyyatı uyğun bir mesajla commit içərisində olur.
- Bir merge commit-inin detallı incələnməsi və nəzərdən keçirilməsi qeyri-adi bir vəziyyətdir, buna görə də bunlardan qaçmaq bütün dəyişikliklərin aid olduqları bir commit-ə sahib olmasını təmin edir.
### Squash (əzmə/birləşdirmə) nə zaman edilməlidir?
"Squashing" bir sıra commit-i götürüb tək bir commit-ə sıxlaşdırmaq prosesidir.
Bəzi hallarda faydalıdır, məsələn:
- Çox az və ya heç bir konteksti olmayan commit-ləri azaltmaq (orfoqrafiya səhvlərinin düzəldilməsi, formatlama, unudulmuş şeylər)
- Birlikdə tətbiq edildikdə daha məntiqli olan ayrıca dəyişiklikləri birləşdirmək
- Üzərində işlənməyə davam edilən commit-ləri yenidən yazmaq
### Rebase və ya squash-dən nə zaman çəkinməlisiniz?
_Public commit_-lərdə və ya bir neçə nəfərin birlikdə işlədiyi paylaşılan branch-lərdə rebase və squash-dən çəkinin. Rebase və squash tarixçəni yenidən yazır və mövcud commit-lərin üzərinə yazır. Bunu paylaşılan branch-lərdə etmək qarışıqlığa səbəb ola bilər (məsələn, uzaq repo-ya push edilən commit-lər və ya digər branch-lərdən gələn commit-lər). Bu, insanların fərqli branch-lər və konfliktlər səbəbindən dəyişikliklərini (həm yerli, həm də uzaq) itirməsinə səbəb ola bilər.
## Faydalı git əmrləri
### rebase -i
Commitləri squash/sıxışdırmaq, mesajları redaktə etmək, commitləri yenidən yazmaq/silmək/sıralarını düzəltmək vs s. üçün istifadə olunur.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Commitləri asanlıqla və daha mürəkkəb bir rebase-ə ehtiyac olmadan təmizləmək üçün istifadə olunur.
[Bu yazıda](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html), necə və nə vaxt ediləcəyinə dair gözəl nümunələr var.
### cherry-pick
Səhv branch-da etdiyiniz commiti yenidən kodlaşdırma etmədən tətbiq etmək lazım olduqda bu çox faydalıdır.
Nümunə:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Deyək ki, aşağıdakı kimi bir _diff_'imiz var:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Credit modeline `use` metodu ekle
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Artıq yazılmış kodu dəyişdirmədən yalnız istədiyimiz yolları əlavə etmək üçün `git add-p` istifadə edə bilərik.
Böyük dəyişikliyi daha kiçik commitlərə bölmək və ya xüsusi dəyişiklikləri sıfırlamaq/kontrol etmək üçün faydalıdır.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Credit modeline `use` metodu ekle
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Digər maraqlı şeylər
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Bəyəndin?
[Təşəkkür et!](https://saythanks.io/to/RomuloOliveira)
## Töhfə vermək
Hər hansı bir yardım təqdirəlayiqdir. Mənə kömək edə biləcəyiniz mövzuların nümunələri:
- Qrammatika və orfoqrafiya düzəlişləri
- Digər dillərə tərcümə
- Mənbə/istinadın təkmilləşdirilməsi
- Yanlış və ya natamam məlumatların düzəldilməsi
## İlham alınanlar, mənbələr və əlavə oxu
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_de-DE.md
================================================
# Commit Messages Guide
[](https://saythanks.io/to/RomuloOliveira)
Ein Leitfaden, um die Wichtigkeit von Commit-Messages zu verstehen und diese richtig zu formulieren.
Verstehe was ein Commit ist, warum es wichtig ist, eine gute Commit-Message zu schreiben, gute Praxis und ein paar Tipps, um eine saubere Commit-Historie zu planen oder vielleicht sogar nachträglich noch anzupassen.
#### Hinweis des Übersetzers
Auch wenn dies eine Übersetzung darstellen soll, empfiehlt es sich, alle Commit-Messages auf Englisch zu schreiben, deshalb sind die Beispiele nicht übersetzt.
## Was ist ein "Commit"?
Ganz einfach beschrieben ist ein Commit eine Art _Schnappschuss_ deiner lokalen Dateien in deinem Repository (dein Projektordner).
Im Gegensatz zur geläufigen Annahme [speichert Git nicht nur die Unterschiede in den Dateien, sondern immer die gesamte Datei (Quelle auf Englisch)](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
Für Dateien, die sich von einem auf den anderen Commit nicht geändert haben, speichert Git lediglich einen Link zur einer bereits gespeicherten Version in einem vorangegangenen Commit.
Die folgende Grafik zeigt wie Git die Daten mit der Zeit speichert. Jede "Version" meint hier einen Commit.
## Warum sind Commit-Messages wichtig?
- Um Code-Reviews zu beschleunigen und zu vereinfachen
- Um die erzielte Änderung besser verstehen zu können
- Um _die_ Gründe zu erläutern, die so nicht aus dem Code hervorgehen (Grundsatzentscheidungen)
- Um zukünftigen Entwicklern zu helfen, zu verstehen, wie und warum Änderungen gemacht wurden – was die Fehlersuche und -behebung vereinfacht
Um diese und noch mehr Vorteile möglichst effizient nutzen zu können, sollten wir uns an die folgenden Praktiken und Standards halten.
## Praktiken
Dies sind Praktiken aus meiner eigenen Erfahrung, sowie aus anderen Artikeln/Anleitungen aus dem Internet. Wenn du noch mehr Tipps hast oder manche dieser Praktiken für nicht sinnvoll hältst, beantrage gerne eine Änderung via Pull Request.
### Imperativ verwenden
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
_Warum soll ich den Imperativ benutzen?_
Eine Commit-Message beschreibt was die Änderung tatsächlich **tut** – ihre Auswirkungen – nicht was vorher war.
### Große Anfangsbuchstaben
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
Diese Regelung ergibt grammatikalisch schlichtweg Sinn, da man den grammatikalischen Regeln bzgl. Großbuchstaben am Satzanfang gerecht wird.
Diese Regelung kann von Entwickler zu Entwickler, Team zu Team oder auch Sprache zu Sprache unterschiedlich sein.
Großschreiben oder nicht, wichtig ist nur, dass man bei einer Variante bleibt.
### Versuche _genau_ zu beschreiben, was die Änderung macht, auch ohne dass man in den Code gucken muss.
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
Dies ist in vielen Situationen (z.B.: mehrere kleine Commits, Refactoring) sinnvoll, um besser zu verstehen, was sich der Entwickler gedacht hat.
### "Warum", "Wozu", "Wie" und andere Details gehören in die Beschreibung der Commit-Message
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are picklable by default
```
```
# Good
Add `use` method to Credit model
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
Titel bzw. Betreff der Commit-Message und die Beschreibung müssen mit einer Leerzeile getrennt werden. Alle weiteren Leerzeilen oder Absätze werden als Teil der Beschreibung gewertet.
Trenn- oder Aufzählungszeichen, wie z.B.: `-`, `*` oder `\` verbessern die Lesbarkeit der Beschreibung.
### Vermeide allgemeingültige oder kontextfreie Beschreibungen
```
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### Limitiere die Länge der Commit-Message
[Es wird empfohlen (Quelle in ENG)](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) maximal 50 Zeichen für den Titel/Betreff und 72 Zeichen für die Nachricht zu verwenden.
### Bleibe in einer Sprache
Dies gilt vor allem für Entwickler, für die Englisch nicht die Muttersprache ist. Logischerweise sollte man sich immer dem etablierten Standard anpassen – ganz besonders bei Repositories mit Entwicklern aus vielen verschiedenen Ländern.
Entscheide dich für eine Sprache und bleibe dabei.
```
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Good (German example)
ababab Fügt die `use` Funktion dem Credit Model hinzu
efefef Nutzt den InventoryBackendPool um aufs Bestands-BackEnd zuzugreifen
bebebe Korrigiert den Methodennamen der InventoryBackend Kind-Klassen
```
```
# Bad (mixes English and German)
ababab Fügt die `use` Funktion dem Credit Model hinzu
efefef Add `use` method to Credit model
cdcdcd Fix method name of InventoryBackend child classes
```
### Template
Das folgende Template, [im Original von Tim Pope (Quelle auf Englisch)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), erschienen so auch in dem Buch [Pro Git Book (Quelle auf Englisch)](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## Rebase vs _Merge_
Dieser Abschnitt ist ein **TL;DR** des lesenswerten Artikels [Atlassian's article Merging vs. Rebasing (Quelle auf Englisch)](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** Wendet die Änderungen des aktuellen Branches auf den Stand des Basis-Branches an.
### _Merge_
**TL;DR:** Erstellt einen neuen Commit, auch _Merge-Commit_, dieser führt die Änderungen beider Branches zusammen.
### Warum bevorzugen manche Entwickler rebase?
Ich persönlich bevorzuge rebase. Gründe dafür sind unter anderem:
* Es entsteht eine "saubere" Historie, ohne unnötige Merge-Commits.
* _What you see is what you get_, z.B.: in eine Code-Review sieht man wirklich jeden Commit. Es sind keine Änderungen in Merge-Commits versteckt.
* Jedes Zusammenführen von Code geschieht einzeln durch den Entwickler, so hat jeder Merge einen eigenen Commit mit einer entsprechenen Commit-Message.
* Im Normalfall werden Merge-Commits in einer Code-Review nicht betrachtet. Hat jede Änderung/Zusammenführung einen eigenen Commit, kann man sicher sein, dass alles an der richtigen Stelle ist und betrachtet werden kann.
### Wann benutzt man squash
Squash beschreibt eine Methode in der eine Reihe von Commits in einem einzelnen Commit zusammengefasst werden.
Hilfreich bei z.B.:
- dem Reduzieren von kleinen/kontextlosen Commits (Rechtschreibfehler, Formatierung, vergessene Änderungen)
- dem Zusammenführen mehrerer Commits, die als Ganzes mehr Sinn ergeben
- dem Neu-Verpacken von _work in progress_ Commits
### Wann sollte man rebase bzw. squash vermeiden
Vermeiden Sie die Verwendung von Rebase und Squash in öffentlichen Commits oder in Branches, in denen mehrere Personen arbeiten.
Rebase und Squash verändern die Historie der Commits und überschreiben bestehende Commits. Verwendet man rebase und squash auf Commits, die sich auf einen gemeinsam genutzten Branch befinden (d.h. Commits, die in ein Remote-Repository verschoben wurden oder von anderen Branches stammen), erzeugt man unötige Verwirrung. Darüber hinaus besteht die Gefahr, dass Andere ihre Änderungen (sowohl lokal als auch auf dem Remote) verlieren, aufgrund von unterschiedlichen Trees und anderen Konflikten.
## Hilfreiche Git Kommandos
### rebase -i
Wird verwendet, um Commits zu squashen, Commit-Messages zu bearbeiten, Neuschreiben/Löschen/Neuordnen von Commits, usw.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
### fixup
Wird verwendet, um Commits einfach anzupassen ohne ein komplexes Rebase durchzuführen.
[Dieser Artikel (Quelle auf Englisch)](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) beschreibt mit Beispielen wie und wann man einen fixup durchführt.
### cherry-pick
Sehr hilfreich, wenn man einen Commit der z.B. versehentlich im falschen Branch gepusht wurde, auf den richtigen Branch anwenden will, ohne diesen neuschreiben zu müssen.
Beispiel:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### git add/checkout/reset [--patch | -p]
Angenommen wir haben die folgenden offenen Änderungen:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in [Pro Git Book](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Mit `git add -p` können wir nun ausschließlich die gewünschten Abschnitte zum Commit hinzufügen, ganz ohne dass wir bestehenden Code ändern müssen. Das ist hilfreich, um größere Änderungen in mehrere kleine Commits aufzuteilen oder um ungewollte Änderungen gezielt rückgängig zu machen.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in [Pro Git Book](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Sonstiges Interessantes
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Hat es dir gefallen?
[Sag danke!](https://saythanks.io/to/RomuloOliveira)
## Mitwirken
Jede Art von Hilfe ist willkommen. Zum Beispiel zu den Themen:
- Grammatik und Rechtschreibung
- Übersetzung in andere Sprachen
- Verbesserung der Quell-Referenzen
- Falsche oder unvollständige Information
## Inspiration, Quellen und Lesenswertes
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_es-AR.md
================================================
# Guía de mensajes de commit
[](https://saythanks.io/to/RomuloOliveira)
Una guía para entender la importancia de los mensajes de commit y cómo escribirlos correctamente.
Aquí vas a aprender qué es un commit, por qué es importente escribir buenos mensajes, buenas prácticas y algunos tips para planear y (re)escribir una buena historia de commits.
## ¿Qué es un "commit"?
En una frase, un commit es una copia instantánea de los archivos escritos de tu repositorio local.
En contra de lo que mucha gente cree, [git no guarda solo la diferencia entre los archivos, sino que guarda cada versión completa](https://git-scm.com/book/es/v2/Inicio---Sobre-el-Control-de-Versiones-Fundamentos-de-Git#_copias_instant%C3%A1neas_no_diferencias)
Para los archivos que no cambian de un commit a otro, git guarda un enlace a la versión previa, idéntica al archivo guardado.
La imagen a continuación muestra como git guarda datos a través del tiempo, entendiendo que cada "versión" es un commit:
## ¿Por qué los mensajes de commit son importantes?
- Para acelerar y dinamizar las revisiones de código
- Para ayudar a entender los cambios
- Para explicar los "por qué" que no pueden ser descritos solo con código
- Para ayudar a los mantenedores futuros a entender por qué o cómo se hizo un cambio, facilitando la resolución de problemas y la depuración
Para maximizar estos resultados se pueden usar las buenas prácticas y estándares descritos en la sección siguiente.
## Buenas prácticas
Estas son algunas prácticas recolectadas desde mi experiencia, artículos de internet y otras guías. Si tienes otras (o estás en contra de alguna) siéntete libre de abrir un Pull Request y contribuir.
### Usa forma imperativa
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
_¿Pero por qué usar forma imperativa?_
Un mensaje de commit describe qué **hace** el cambio referenciado, su efecto, no qué se hizo.
### Primera letra en mayúscula
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
El motivo detrás de esto es para seguir la regla gramatical que las oraciones deben comenzar en mayúsculas.
El uso de esta práctica puede variar de persona a persona, de equipo a equipo, o incluso de idioma a idioma.
Mayúsculas o no, es importante adherir a un solo estándar y respetarlo.
### Comunica qué hace el cambio sin necesidad de mirar al código fuente
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
Es muy útil para ayudar a los revisores a entender el razonamiento del autor de los cambios (por ejemplo, cuando hay muchos commits, muchos cambios y refactors)
### Usa el cuerpo del mensaje para explicar "por qué", "para qué", "cómo" y detalles adicionales
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are picklable by default
```
```
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
El asunto y el cuerpo del mensaje se separan por una línea en blanco.
Las líneas en blanco adicionales pasan a ser consideradas parte del cuerpo del mensaje.
Caracteres como `-`, `*` y \` pueden aportar legibilidad.
### Evita mensajes genéricos o sin contexto
```
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### Limita el número de columnas
[Se recomienda](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto#r_commit_guidelines) usar un máximo de 50 caracteres para el asunto y 72 para el cuerpo.
### Mantén idioma consistente
Para dueños de proyectos: elijan un idioma y escriban todos los mensajes de commit usando ese idioma. Idealmente debería coincidir con los comentarios del código, la localización por defecto (para proyectos que apliquen), etc.
Para contribuidores: escriban sus mensajes de commits usando el mismo idioma que los que ya existen en el historial de commits.
```
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Good (Spanish example)
ababab Agrega el método `use` a la clase Credit
efefef Usa el InventoryBackendPool para recuperar el backend de stock
bebebe Corrige el nombre de un método de la clase InventoryBackend
```
```
# Bad (mixes English and Spanish)
ababab Use InventoryBackendPool to retrieve inventory backend
efefef Add `use` method to Credit model
cdcdcd Listo
```
### Plantilla
Esta es una plantilla, [escrita originalmente por Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), que aparece en el [_Libro Pro Git_](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto).
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## Rebase vs. Merge
Esta sección es un **TL;DR** del excelente tutorial de Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** aplica los commits de tu rama, uno a uno, sobre la rama base, generando un nuevo árbol.
### Merge
**TL;DR:** crea un nuevo commit, llamado (adecuadamente) un _commit de merge_, con la diferencia entre las dos ramas.
### ¿Por qué algunas personas prefieren rebase en lugar de merge?
Yo particularmente prefiero rebase por sobre merge. Entre otros, los motivos son:
* Genera una historia más "limpia", sin commits de merge innecesarios
* _Lo que ves es lo que hay_, por ejemplo, en una revisión de código los cambios vendrán de commits específicos y rotulados, evitando cambios ocultos en commits de merge
* Más merges son resueltos por el autor y cada cambio producto de un merge es un commit separado con un mensaje acorde.
* No es una práctica usual indagar y revisar un commit de merge, así que al evitarlos nos aseguramos que los cambios provengan de un commit particular
### ¿Cuándo hacer squash?
"Squashing" es el proceso de tomar una serie de commits y condensarlos en uno solo.
Es útil en varias situaciones, por ejemplo:
- Reducir commits muy pequeños o sin contexto (typos, formateos, olvidos)
- Unir cambios separados que cobran más sentido cuando se aplican juntos
- Reescribir commits de trabajo en progreso (WIP)
### ¿Cuándo evitar el rebase o squash?
Evita el uso de rebase y squash en commits que sean públicos o compartidos por varias personas que trabajan en simultáneo.
Rebase y squash reescriben la historia y sobreescriben commits existentes, al hacerlo en commits que pertenecen a ramas compartidas (por ejemplo que fueron publicados en un repositorio remoto) puede causar confusión y pérdida del trabajo de alguien (tanto de manera local como remota) por encontrarnos frente a árboles divergentes y conflictos.
## Comandos git útiles
### rebase -i
Úsalo para hacer squash de commits, editar mensajes, reescribir/eliminar/reordenar commits, etc.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Úsalo para limpiar commits fácilmente y sin necesidad de un rebase más complejo.
[Este artículo](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) tiene muy buenos ejemplos de cómo y cuándo usarlo.
### cherry-pick
Es útil para aplicar un commit que se hizo en una rama equivocada, sin necesidad de volver a escribirlo.
Ejemplo:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Supongamos que tenemos la siguiente diferencia:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Podemos usar `git add -p` para agregar solo los parches que querramos, sin necesidad de cambiar el código que ya fue escrito.
Es útil también para separar un cambio grande en commits pequeños o hacer reset/checkout de cambios específicos.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Otros enlaces interesantes
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## ¿Te gustó?
[¡Di gracias!](https://saythanks.io/to/RomuloOliveira)
## Contribuciones
Toda ayuda es bienvenida. Ejemplo de temas sobre los que puedes colaborar:
- Correcciones de gramática y ortografía
- Traducción a otros idiomas
- Mejoras en el código de referencia
- Información incorrecta o incompleta
## Fuentes de inspiración, referencias y lecturas adicionales
- [Cómo escribir un mensaje de commit de git](https://chris.beams.io/posts/git-commit/)
- [Libro Pro Git - Guía de commits](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto#r_commit_guidelines)
- [Una nota sobre mensajes de commit de git](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Libro Pro Git - Reescribiendo la Historia](https://git-scm.com/book/es/v2/Herramientas-de-Git-Reescribiendo-la-Historia)
================================================
FILE: README_fa-IR.md
================================================
# راهنمای Commit-Message
[](https://saythanks.io/to/RomuloOliveira)
‫
راهنمایی برای درک اهمیت Commit-Message و نحوه نوشتن صحیح آن.
‫
این راهنما سعی دارد به شما کمک کند یادبگیرید کامیت چیست، چرا نوشتن Commit-Message مناسب مهم است،
تمرین های خوب و نکاتی که می تواند منجرب به بازنگری و داشتن تاریخچه کامیت بهتری شود
## دیگر زبان ها
- [English](README.md)
- [Português](README_pt-BR.md)
- [Deutsch](README_de-DE.md)
- [Español](README_es-AR.md)
- [Italiano](README_it-IT.md)
- [한국어](README_ko-KR.md)
- [Русский](README_ru-RU.md)
- [简体中文](README_zh-CN.md)
- [日本語](README_ja-JP.md)
- [Українська](README_ua-UA.md)
- [پارسی](README_fa-IR.md)
## "Commit" چیست ?
‫
به زبان ساده، یک کامیت اسنپ شات ی از فایل های محلی شما هست که در مخزن محلی نوشته میشود
برخلاف تصور افراد، [گیت تنها تغییرات فایل هارا نگهداری نمی کند بلکه نسخه کاملی از آنها را نگهداری میکند](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
و برای فایل هایی که تغییری در آنها داده نشده تنها لینک منطبق با فایل موجود را نگهداری میکند.
تصویر زیر نحوه ذخیره اطلاعات درطول زمان را نمایش میدهد، در اینجا هر نسخه یک کامیت محسوب میگردد
## چرا Commit-Messages اهمیت دارند؟
- سرعت بخشیدن و ساده سازی کدریویو
- کمک به فهم تغییرات
- توضیح "دلیل"، که تنها با کد قابل توضیح نیست
- کمک به نگهداری درآینده و فهم چرا و چگونه تغیرات داده شده اند، عیب یابی و اشکال زدایی سریعتر
برای درک بهتر، چند تمرین و استاندارد در قسمت بعدی توضیح داده خواهد شد
## تمرین خوب
اینها چند تمرین خوب گردآوری شده از تجارب شخصی، اینترنت و سایر راهنماها می باشند، اگه شما با آنها مخالفید یا میتوانید تمرین های بهتر دیگری ارائه دهید میتوانید در توسعه این مخزن مشارکت نمایید
### استفاده از فرم دستوری
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
_اما چرا ما شکل دستوری را استفاده میکنیم?_
‫
یک Commit-Message درواقع آن چیزی راکه تغییرات انجام میدهد یا تاثیر آن را توضیح میدهد نه چیزی که انجام شده است
### حرف اول با حروف بزرگ
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
دلیل اینکه اولین حرف باید با حروف بزرگ باشد پیروی از قانون گرامر و استفاده از حروف بزرگ در ابتدای جمله می باشد
استفاده از این تمرین از شخصی به شخص دیگر، یا از تیمی به تیمی دیگر یا حتی از زبانی به زبان دیگر متفاوت خواهد بود.
استفاده از حروف بزرگ یا کوچک اهمیتی ندارد، نکته مهم پیروی از یک قانون واحد است
### سعی در رساندن اینکه تغیر چه کاری انجام میدهد بدون نیاز به مشاهده کد
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
در بسیاری از سناریوها مانند کامیت های متعدد، تغییرات مختلف و بازنویسی به بازبینی کننده کمک خواهد کرد که بفهمد کامیت کننده درچه فکری بوده است
### استفاده از بدنه Commit-Message برای توضیح "چرا"، "به چه علت"، "چطور" و جزئیات بیشتر
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
‫
موضوع و بدنه پیام کامیت با یک خط خالی جدا می شوند.
خط های خالی اضافی جزئی از بدنه Commit-Message محسوب خواهند شد
‫
کارکتر هایی همچون `-`, `*` و `\` باعث تقویت خوانایی Commit-Message خواهند شد
### از متن های کلی یا بی محتوا دوری کنید
```
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### تعداد کارکتر های مورد استفاده را محدود کنید
‫
[توصیه شده](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) برای موضوع Commit-Message حداکثر 50 کارکتر و برای بدنه آن کداکثر 72 کارکتر استفاده شود.
### در استفاده از زبان نوشتن متن ثابت قدم باشید
‫
برای مالک پروژه: انتخاب یک زبان و نوشتن همه Commit-Message ها بوسیله آن، که باید همان زبان مورد استفاده برای کامنت ها و زبان پیش فرض برای پروژه های چند زبانه باشد
‫
برای مشارکت کنندگان: نوشتن Commit-Message با زبان مشابه متن های کامیت قبلی
```
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Good (Portuguese example)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### قالب
‫
این یک قالب [نوشته شده توسط Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) که در [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) قابل دسترسی می باشد
```
تغیرات را در حدود ۵۰ کاراکتر یا کمتر خلاصه کنید
متن توضیحات دقیقتر را در ۷۲ کاراکتر بگنجانید،
.اولین خط بعنوان موضوع و مابقی بعنوان بدنه تلقی خواهد شد
یک خط خالی برای جدا کردن موضوع از بدنه ضرروی خواهد بود
در غیراینصورت ابزارهای مختلف مثل `log`, `shortlog`و `rebase` سردرگم خواهند شد
مشکلی که کامیت فوق رفع خواهد کرد را توضیح دهید
برخلاف اینکه چطور تغییرات انجام شده برروی چرا تغییرات رو انجام داده اید
فوکوس کنید.
اینکه تغییرات چطور انجام شده در کد مشخص هست
اینجا مکانی هست که باید توضیح دهید آبا تغیرات تاثیری بر قسمت های مختلف یا عواقب ناخواسته ای خواهند داشت
اگر از ابزاری برای مدیریت ایژوهااستفاده می کنید شماره ارجاع مربوط را در انتهای متن قرار بدید
مثال
Resolves: #123
See also: #456, #789
```
اینجا میتوانید متن اصلی را مشاهده نمایید
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## Rebase vs. Merge
‫
این قسمت خلاصه ای از آموزش عالی اطلسین می باشد، ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
بطور خلاصه قرار دادن کامیت های برنچ شما برروی کامیت های مستر وتولید درخت جدید
### Merge
‫
بطور خلاصه ایجاد یک کامیت جدید بنام _merge commit_ شامل اختلاف دو برنچ
### چرا افراد Rebase را به Merge ترجیح میدهند؟
من شخصا ریبیس را به مرج ترجیح میدهم به دلایل زیر
* توسط آن یک تاریخچه کامیت تمیز و بدون کامیت مرج غیرضروری خواهید داشت
* چیزی که شما می بینید چیزی هست که بدست میاورید به این معنی که در بازنگری همه تغییرات در کامیت مربوطه قابل مشاهده هستند وتغییراتی در کامیت مرج مخفی نشده است
* مرجج های بیشتری توسط کامیت کننده برطرف خواهد شد و هر تغییر مرج در کامیتی با متن مناسب خواهد بود
* در حالت عادی کامیت های مرج بررسی نمیشوند بنابراین اجتناب از آنها این اطمینان به ما خواهد داد که همه تغییرات در کامیت مربوطه خواهند بود
### چه وقت از squash استفاده کنیم
‫
"Squashing" پروسه ای می باشد که یک سری ازکامیت ها به یک کامیت تبدیل خواهند شد
و در وضعیت های مختلفی مفید می باشد مانند
- کاهش تعداد کامیت های بدون محتوا یا کم محتوا مانند اصلاحات تایپی، فرمت کد، چیزهای فراموش شده
- اضافه کردن تغییراتی که درصورت یکی شدن معنی دار خواهند بود
- بازنویسی کامیت های _work in progress_
### چه زمانی از rebase یا squash استفاده نکنیم?
در زمانی که برروی برنچ های مشترک یا کامیت های عمومی با سایر افراد کار میکنید باید از استفاده از آنها اجتناب کنید
این دستورات تاریخچه کامیت ها را بازنویسی همچنین کامیت های موجود رااز بین خواهد برد
در نتیجه انجام آن برروی برنچ های مشترک می تواند باعث ابهام و یا ازدست رفتن تغییرات بدلیل کانفلیک یا انشعابات در درخت کامیت ها گردد
## دستورات مفید Git
### rebase -i
از این دستور برای ویرایش کامیت، ریبیس، بازنویسی، حذف یا تغییر ترتیب کامیت ها بطور مثال میتوانید استفاده کنید
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
‫
از این دستور برای پاک سازی آسان بدون نیاز به پیچیدگی های زیاد rebase می توانید استفاده کنید
[این مقاله](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) در بردارنده مثال هایی مفیدی از نحوه و زمان انجام آن می باشد
### cherry-pick
دستور مفیدی برای اضافه کردن کامیتی که در برنچی اشتباهی انجام شده بدون نیاز به کدنویسی مجدد
Example:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
بطور مثال ما تفاوت زیر را داریم:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
‫
توسط `git add -p` ما میتوانید تنها پچ هایی که میخواهیم اضافه کنیم،
بدون احتیاج به تغیر کدی که نوشته شده است
همچنین این امکان میسر خواهند بود تغییرات بزرگ به کامیت های کوچکتر شکسته شود یا تغیرات reset/checkout شوند
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## سایت های جالب دیگر
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## مفید بود?
[تشکر !](https://saythanks.io/to/RomuloOliveira)
## مشارکت
از هر نوع کمکی قدردانی خواهد شد بطور مثال در موارد زیر شما میتوانید به بنده کمک کنید
- گرامر و تصحیح املا
- ترجمه به زبان های دیگر
- تقویت منابع و مراجع
- اصلاعات ناقص و نادرست
## منابع الهام گرفته شده و اطلاعات بیشتر
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_fr-FR.md
================================================
# Guide sur les messages de commit
[](https://saythanks.io/to/RomuloOliveira)
Un guide pour comprendre l'importance des messages de commit et comment bien les écrire.
Cela pourrait vous aider à comprendre ce qu'un commit est, pourquoi c'est important de bien écrire ses messages, les meilleurs techniques et quelques astuces, pour mieux (ré)écrire une bonne "commit history"
## Qu'est-ce qu'un "commit" ?
Dans des termes simples, un commit est une _sauvegarde_ de vos fichiers locaux, écrits dans votre dépôt local.
Contrairement à ce que certaines personnes pensent, [git ne stocke pas seulement la différence entre ces fichiers, il stocke une version complète de tous les fichiers](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
Pour les fichiers qui ne changent pas d'un commit à l'autre, git stocke juste un lien vers la version précédente identique qui est déjà stockée.
L'image ci-dessous montre comment git stocke les fichiers à travers le temps, dans quelle "Version" est un commit.
## Pourquoi les messages de commit sont importants ?
- Pour raccourcir et faciliter les revues de code.
- Pour aider dans la compréhension d'un changement.
- Pour expliquer les "pourquoi", qui ne sauraient être décris en code
- Pour aider les futurs personnes qui vont devoir maintenir le code à comprendre les différents changements, et l'évolution du code.
Pour maximiser ces résultats, nous pouvons utiliser certaines bonnes pratiques et des standards, décrits dans la prochaine section.
## Bons usages
Il y a quelques bons usages recueillit par l'experience, des articles sur internet, et d'autres guides. Si vous en avez d'autres (ou n'êtes pas d'accord avec certains), soyez libres d'ouvrir une demande de Pull et de contribuer à l'amélioration du guide.
### Utilisez l'impératif
```
# Bon
Use InventoryBackendPool to retrieve inventory backend
```
```
# Mauvais
Used InventoryBackendPool to retrieve inventory backend
```
_Pourquoi l'impératif ?_
Un message de commit décrit ce que le changement **fait**, ces effets, pas ce qui à été fait.
### Mettre une majuscule au début de la phrase
```
# Bon
Add `use` method to Credit model
```
```
# Mauvais
add `use` method to Credit model
```
On met la première lettre en majuscule pour suivre la règle de grammaire selon laquelle on doit utiliser une majuscule au début d'une phrase.
Cette pratique peut être ou non appliquée en fonction des personnes, des équipes ou même des languages. Dans tous les cas, l'important est de définir une règle et de s'y tenir.
### Essayer de décrire les changements sans avoir à lire le code
```
# Bon
Add `use` method to Credit model
```
```
# Mauvais
Add `use` method
```
```
# Bon
Increase left padding between textbox and layout frame
```
```
# Mauvais
Adjust css
```
Cela est utile dans de nombreux scenarios (commits multiples, beaucoup changements et refactorisations) pour aider les reviewers à comprendre ce à quoi la personne qui a fait le commit pensait.
### Use the message body to explain "why", "for what", "how" and additional details
### Utiliser le corps du message pour expliquer "pourquoi", pour "quoi", "comment" et autres détails
```
# Bon
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because cart was calling the backend implementation
incorrectly.
```
```
# Bon
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are picklable by default
```
```
# Bon
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
L'objet et le corps du message sont séparés par un saut de ligne.
Des sauts de ligne additionels sont considérés comme faisant partie du corps.
Eviter les caractères tels que `-`, `*` et `\` améliore la lisiblité.
### Eviter les messages génériques ou sans aucun contexte
```
# Mauvais
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### Limiter le nombre de colonnes
[Il est recommandé](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) d'utiliser un maximum de 50 caractères pour le sujet, et 72 pour le corps.
### Garder la cohérence linguistique
Pour les propriétaires de projet: Choisissez une langue et écrivez tous les messages de validation en utilisant cette langue. Idéalement, il devrait correspondre aux commentaires de code, aux paramètres régionaux de traduction par défaut (pour les projets localisés), etc.
Pour les contributeurs: Écrivez vos messages de validation en utilisant la même langue que l'historique de validation existant.
```
# Bon
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Bon (Exemple Portugais)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Bad (mix Anglais et Portugais)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Modèle
C'est un modèle, [écrit par Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), qui apparait dans le [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Résumer les changements en 50 caractères ou moins.
Texte explicatif plus détaillé, si nécessaire. Mettez un retour à la ligne à environ 72 caractères. Dans certains contextes, la première ligne est traitée
en tant que sujet du commit et le reste en tant que corps. La ligne
vide séparant le sommaire du corps est critique (sauf si vous omettez complètement le corps); certains outils tels que `log`, `shortlog` et
`rebase` peuvent être confus si vous les fusionnez ensemble.
Expliquez le problème que ce commit est en train de résoudre. Concentrez-vous sur
les raisons pour lesquelles vous apportez ce changement, par opposition à la
façon dont (le code explique cela).
Est-ce qu'il y at-il des effets secondaires ou d’autres conséquences non intuitives de ce changement? Voici l'endroit pour les expliquer.
Les autres paragraphes viennent après les lignes vides.
- Les puces sont ok.
- Généralement, un tiret ou un astérisque est utilisé pour la puce, précédé d'un espace, avec des lignes vides entre les deux, mais les conventions varient ici.
Si vous utilisez un outil de suivi des problèmes,
mettez les références à la fin comme ceci:
Résout: #123
Voir aussi: #456, #789
```
## Rebase vs. Merge
Cette section est un **TL;DR** de l'excellent tutoriel d'Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** Applique vos commits de branche, un par un, sur la branche principale, générant un nouvel "arbre"
### Merge
**TL;DR:** Créé un nouveau commit, appelé un _merge commit_, avec les différences entre ces deux branches.
### Pourquoi certaines personnes préfères rebase plutôt que merge ?
Je préfère particulièrement rebase plutôt que merge. Les raisons sont:
* Cela génère un historique "propre", sans merge commits inutiles.
* Ce que vous voyez est ce que vous obtenez, c’est-à-dire que dans une revue de code, toutes les modifications proviennent d’un commit spécifique, évitant les changements masqués dans les commits de merge.
* Plus de merges sont résolus par la personne qui commit, et chaque modification de merge est dans un commit avec un message propre à celui-ci.
* Il est inhabituel de chercher et d'examiner les commits de merge. Evitez-les donc pour vous assurer que tous les changements ont un commit auquel ils appartiennent.
### Quand "squash"
"Squashing" est le processus consistant à prendre une série de commits et à les condenser en un seul commit.
C'est utile dans plusieurs situations, e.g.:
- Réduire le nombre de commit avec peu ou pas de contexte (correction de fautes d'orthographe, formatage, choses oubliées)
- Joindre des modifications distinctes qui ont plus de sens lorsqu'elles sont appliquées ensemble
- Réécrire les commits de _travail en cours_
### Quand éviter rebase ou squash ?
Il faut éviter rebase et squash dans les commits publiques ou dans les branches partagées où plusieurs personnes travaillent dessus.
Rebase et squash réécrivent l'historique et écrasent les commits existants, le faire sur des commits qui sont dans des branches partagées (i.e., les commits push sur le dépôt distant ou qui viennent d'autres branches) peut entrainer de la confusion, et les gens risquent de perdre leurs changements (autant localement que à distance) car les arbres et les conflicts divergent.
## Commandes git pratiques
### rebase -i
Utilisez-la pour squash les commits, modifier les messages, réécrire/supprimer/réorganiser les commits, etc.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Utilisez-la pour nettoyer les commits facilement et sans nécessiter de rebase plus complexe.
[Cet article](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) a de bons exemples de comment et quand le faire.
### cherry-pick
C'est très utile pour appliquer le commit que vous avez fait sur la mauvaise branche, sans qu'il soit nécessaire de le coder à nouveau.
Exemple:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Imaginons que nous avons le diff suivant:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Modèle
+
+C'est un modèle, [Ecrit par Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), qui apparait dans [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contribuer
Toute sorte d'aide est apréciée. Voici quelques exemples de sujets où vous pouvez m'aider.
@@ -202,3 +205,4 @@ Toute sorte d'aide est apréciée. Voici quelques exemples de sujets où vous pouvez m'aider.
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
On peut utiliser git add -p pour ajouter uniquement les correctifs que nous voulons, sans qu'il soit nécessaire de modifier le code déjà écrit.
Il est utile de scinder un gros changement en de plus petits commits ou de réinitialiser/extraire des modifications spécifiques.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## D'autres choses intéréssantes
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Vous aimez ?
[Dites merci!](https://saythanks.io/to/RomuloOliveira)
## Contribuer
Toute sorte d'aide est appréciée. Voici quelques exemples de sujets où vous pouvez m'aider :
- Corrections grammaticales et orthographiques
- Traduction dans d'autres langues
- Meilleures référencement des sources
- Informations incorrectes ou incompletes
## Inspirations, sources et lectures complémentaires:
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_gr-GR.md
================================================
# Οδηγός για τα "Μηνύματα Commit"
[](https://saythanks.io/to/RomuloOliveira)
Αυτό το κείμενο αποτελεί έναν οδηγό που θα συντελέσει στο να κατανοήσετε την σημασία των μηνυμάτων commit και πώς να τα γράψετε σωστά.
Ενδεχομένως να σας βοηθήσει να μάθετε τι ακριβώς είναι ένα commit, γιατί θεωρείται σημαντικό το να γράφετε καλά μηνύματα, βέλτιστες πρακτικές και κάποιες συμβουλές για το πώς να προσχεδιάσετε και (ξανά)συντάξετε ένα καλό ιστορικό commit.
## Τι είναι ένα "commit"?
Με απλά λόγια, ένα commit είναι ένα _στιγμιότυπο_ των τοπικών σας αρχείων, γραμμένο στο τοπικό σας απωθητήριο(repository).
Αντίθετα με την γνώμη μερικών, [το git δεν αποθηκεύει μόνο την εκάστοτε διαφορά μεταξύ των αρχείων, αποθηκεύει μία πλήρη έκδοση όλων των αρχείων](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
Όσον αφορά τα αρχεία τα οποία δεν άλλαξαν από το ένα commit στο άλλο, το git αποθηκεύει μόνο έναν σύνδεσμο που παραπέμπει στο προηγούμενο, πανομοιότυπο αρχείο που είναι ήδη αποθηκευμένο.
Η παρακάτω εικόνα αναπαριστά τον τρόπο σύμφωνα με τον οποίο το git αποθηκεύει δεδομένα με την πάροδο του χρόνου, όπου κάθε "Εκδοχή" είναι ένα commit:
## Γιατί είναι τα μηνύματα commit σημαντικά?
- Για να επιταχυνθούν και βελτιστοποιηθούν οι κριτικές κώδικα
- Για να συνδράμουν στην καλύτερη κατανόηση μιας αλλαγής
- Για να εξηγήσουν "τα γιατί (αίτια)" που δεν μπορούν να περιγραφτούν μόνο με την χρήση κώδικα
- Για να βοηθήσουν μελλοντικούς διατηρητές του απωθητηρίου να καταλάβουν γιατί και πώς υλοποιήθηκαν ορισμένες αλλαγές, κάτι που καθιστά την επίλυση προβλημάτων και τον εντοπισμό "bugs" ευκολότερα
Για να επιτύχουμε αυτά τα αποτελέσματα στον μέγιστο βαθμό, μπορούμε να χρησιμοποιήσουμε ορισμένες καλές πρακτικές και πρότυπα που αναλύονται στο επόμενο τμήμα.
## Καλές πρακτικές
Αυτές είναι μερικές πρακτικές που συνέλεξα από τις εμπειρίες μου, άρθρα στο διαδίκτυο, και άλλους οδηγούς. Εάν έχετε άλλες (ή διαφωνείτε με μερικές) νιώστε ευπρόσδεκτοι να ανοίξετε ένα "Pull Request" και να συνεισφέρετε.
### Χρησιμοποιήστε υποτακτική
```
# Καλό
Χρησιμοποιώ InventoryBackendPool για να επανακτήσω inventory backend
```
```
# Κακό
Χρησιμοποίησα InventoryBackendPool για να επανακτήσω inventory backend
```
_Αλλά γιατί να χρησιμοποιήσω υποτακτική;_
Ένα μήνυμα commit περιγράφει τι η αναφερθείσα αλλαγή **κάνει** στην πραγματικότητα, τις επιδράσεις της, όχι τι συνέβη.
### Κάντε το πρώτο γράμμα κεφαλαίο
```
# Καλό
Προσθέσει την `use` μέθοδο στο Credit μοντέλο
```
```
# Κακό
προσθέσει την `use` μέθοδο στο Credit μοντέλο
```
Ο λόγος για τον οποίο πρέπει να είναι το πρώτο γράμμα κεφαλαίο είναι για να ακολουθηθεί ο κανόνας της γραμματικής που δηλώνει ότι πρέπει να χρησιμοποιούνται κεφαλαία γράμματα στην αρχή των προτάσεων.
Η χρήση αυτής της πρακτικής ενδέχεται να ποικίλλει από άτομο σε άτομο, ομάδα σε ομάδα, ή ακόμα από γλώσσα σε γλώσσα.
Με κεφαλαίο πρώτο γράμμα ή όχι, το σημαντικό είναι να παραμείνετε στο να χρησιμοποιείτε ένα μόνο πρότυπο και να το ακολουθήσετε.
### Προσπαθήστε να επικοινωνήσετε τι κάνει η εκάστοτε αλλαγή χωρίς να απαιτείται αναδρομή στον πηγαίο κώδικα
```
# Καλό
Προσθέσει την `use` μέθοδο στο Credit μοντέλο
```
```
# Κακό
Προσθέσει την `use` μέθοδο
```
```
# Καλό
Αυξήσει το αριστερό κενό μεταξύ του textbox και layout frame
```
```
# Κακό
Προσαρμόσει το css
```
Είναι λυσιτελές σε πολλές εκδοχές (π.χ. πολλαπλά commits, διάφορες αλλαγές και refactors) το να βοηθήσετε τους κριτικούς κώδικα να καταλάβουν τι σκεφτόταν αυτός που διέπραξε τα commits.
### Χρησιμοποιήστε το σώμα κειμένου για να εξηγήσετε "γιατί", "για ποιον σκοπό", "πώς" και επιπρόσθετες λεπτομέρειες
```
# Καλό
Φτιάξει όνομα μεθόδου των παιδιών κλάσεων του InventoryBackend
Οι κλάσεις που εξήγοντο από το InventoryBackend δεν
σέβοταν το βασικό interface της κλάσης.
Δούλεψε επειδή το cart καλούσε την υλοποίηση
backend με λάθος τρόπο.
```
```
# Καλό
Μετατρέψει τα credits σε σειριακά και αντίστροφα ως json στο Cart
Μετατροπή των Credit instances σε dict για δύο κύριους λόγους:
- Το Pickle στηρίζεται στο file path για τις κλάσεις και δεν θέλουμε να
χαλάσουμε τα πάντα εφ' όσον χρειαστεί ένα refactor
- Το dict και οι ενσωματομένοι τύποι είναι δυνατόν να γίνουν
pickled από μόνοι τους
```
```
# Καλό
Προσθέσει την `use` μέθοδο στο Credit
Αλλαγή από namedtuple σε κλάση γιατί χρειαζόμαστε να
εγκατασταστήσουμε ένα καινούργιο attribute (in_use_amount)
με μία νέα τιμή
```
Το θέμα και το σώμα των κειμένων διαχωρίζονται μέσω μίας κενής γραμμής.
Περαιτέρω κενές γραμμές εκλαμβάνονται ως μέρος του σώματος κειμένου.
Χαρακτήρες όπως `-`, `*` και \` είναι στοιχεία που βελτιώνουν την αναγνωσιμότητα.
### Αποφύγετε γενικού ύφους μηνύματα ή μηνύματα χωρίς κάποιο γενικό πλαίσιο
```
# Κακό
Φτιάξει αυτό
Φτιάξει πράγματα
Τώρα πρέπει να δουλέψει
Αλλάξει πράγματα
Τροποποιήσει το css
```
### Περιορίστε τον αριθμό των χαρακτήρων
[Προτείνεται](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) να χρησιμοποιείτε ένα μέγιστο 50 χαρακτήρων για το θέμα και 72 για το σώμα του κειμένου
### Διατηρήστε συνοχή στην γλώσσα
Για τους ιδιοκτήτες project: Διαλέξτε μία γλώσσα και γράψτε όλα τα μηνύματα commit χρησιμοποιώντας αυτήν την γλώσσα. Ιδανικά, θα πρέπει να ταιριάζει με τα σχόλια στον κώδικα, το προκαθορισμένο locale μετάφρασης (για projects τοπικού χαρακτήρα), κτλ.
Για όσους συνεισφέρουν: Γράψτε τα μηνύματα commit σας χρησιμοποιώντας την ίδια γλώσσα που χρησιμοποιείται στο ήδη υπάρχον ιστορικό commit.
```
# Καλό
ababab Προσθέσει την `use` μέθοδο στο μοντέλο Credit
efefef Χρησιμοποιήσει το InventoryBackendPool για να επανακτήσει το inventory backend
bebebe Διορθώσει το όνομα των μεθόδων των InventoryBackend παιδιών κλάσεων
```
```
# Καλό (Παράδειγμα στα Πορτογαλικά)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Κακό (Μπλέκει Αγγλικά και Πορτογαλικά)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Πρότυπο
Αυτό είναι ένα πρότυπο, [που αρχικά έγραψε ο Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), το οποίο εμφανίζεται στο [_Pro Git Βιβλίο_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Αναφέρετε περιληπτικά τις αλλαγές σε περίπου 50 χαρακτήρες ή λιγότερους
Πιο λεπτομερές επεξηγηματικό κείμενο, εάν κρίνεται απαραίτητο.
Συμπυκνώστε το σε περίπου 72 χαρακτήρες. Εντός κάποιων πλαισίων,
η πρώτη γραμμή αντιμετωπίζεται ως το θέμα του commit και το υπόλοιπο
του κειμένου ως το σώμα του. Η κενή γραμμή που διαχωρίζει την
περίληψη από το σώμα είναι ζωτικής σημασίας (εκτός και αν παραλείψετε
το σώμα εντελώς); ποικίλια εργαλεία όπως τα `log`, `shortlog` και `rebase`
μπορεί να μπερδευτούν αν τρέξετε τα δύο μαζί.
Εξηγήστε το πρόβλημα που επιλύει αυτό το commit. Εστιάστε στο γιατί
κάνετε αυτήν την αλλαγή αντί στο πώς (ο κώδικας το εξηγεί αυτό).
Υπάρχουν έμμεσες επιδράσεις ή άλλες μη διαισθητικές συνέπειες αυτής
της αλλαγής; Εδώ είναι το μέρος για να τις εξηγήσετε.
Περαιτέρω παράγραφοι έρχονται μετά από κενές γραμμές.
- Τα bullet points είναι, και αυτά, εντάξει
- Συνήθως για το bullet χρησιμοποιείται μία παύλα ή ένας αστερίσκος,
μετά από ένα μόνο κενό, με κενές γραμμές ανάμεσα, αλλά οι συμβάσεις
σχετικά με αυτό το θέμα ποικίλουν.
Άμα χρησιμοποιείτε έναν issue tracker, τοποθετήστε αναφορές σε αυτούς
στο κάτω μέρος, όπως έτσι:
Επιλύει: #123
Δείτε επίσης: #456, #789
```
## Rebase εναντίον Merge
Αυτό το τμήμα είναι ένα **TL;DR** του εξαιρετικού tutorial του Atlassian, ["Merging εναντίον Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** Εφαρμόζει τα commits στο κλαδί που είστε, ένα ένα, στο κλαδί βάση, παράγοντας ένα καινούργιο δέντρο.
### Merge
**TL;DR:** Δημιουργεί ένα νέο commit, το επονομαζόμενο (δικαίως) _merge commit_, με τις διαφορές μεταξύ των δύο κλαδιών.
### Γιατί μερικοί προτιμούν να κάνουν rebase αντί για merge;
Εγώ προσωπικά προτιμώ να κάνω rebase αντί για merge. Οι λόγοι περιλαμβάνουν:
* Παράγει ένα "καθαρό" ιστορικό, χωρίς αχρείαστα merge commits
* _Ότι δείτε είναι ότι παίρνετε_, δηλαδή, σε μια κριτική κώδικα όλες οι αλλαγές προέρχονται από ένα συγκεκριμένο και ονοματιζμένο commit, αποφεύγοντας αλλαγές κρυμμένες μέσα σε merge commits
* Περισσότερα merges επιλύονται από αυτόν που κάνει commit, και κάθε αλλαγή merge είναι σε ένα commit με ένα κατάλληλο μήνυμα
* Είναι ασηνύθιστο να ψάχνεις και να κάνεις κριτική κώδικα σε merge commits, οπότε το να τα αποφεύγεις διασφαλίζει το ότι όλες οι αλλαγές έχουν ένα commit στο οποίο ανήκουν
I particularly prefer to rebase over merge. The reasons include:
### Πότε να κάνετε squash
"Squashing" είναι η διαδικασία του να παίρνεις μια ακολουθία από commits και μετά να τις συμπυκνώνεις σε ένα μόνο commit.
Είναι χρήσιμο σε πληθώρα περιστάσεων, π.χ:
- Ελλάτωση commits με λίγο ή καθόλου πλαίσιο (διορθώσεις τυπογραφικών λαθών, formatting, ξεχασμένα πράγματα)
- Σύντμηση διαφορετικών αλλαγών που βγάζουν περισσότερο νόημα όταν εφαρμοστούν μαζί
- Γράψιμο έτη μία φορά _work in progress_ commits
### Πότε να αποφύγετε το rebase ή το squash;
Αποφύγετε τα rebase και squash σε δημόσια commits ή σε κοινόχρηστα κλαδιά όπου δουλεύουν πολλοί άνθρωποι.
Το rebase και το squash ξανά γράφουν το ιστορικό και γράφονται επί των ήδη υπαρχόντων commits, το να τα κάνετε σε commits που είναι σε κοινόχρηστα κλαδιά (δηλαδή, commits που έχετε κάνει push σε remote απωθητήριο ή που προέρχονται από κλαδιά άλλων) μπορεί να προκαλέσει σύγχηση και ενδέχεται άνθρωποι να χάσουν τις αλλαγές τους (και τοπικά και remotely) λόγω των αποκλίνοντων δέντρων και conflicts.
## Χρήσιμες εντολές git
### rebase -i
Χρησιμοποιήστε την για να κάνετε squash commits, να επεξεργαστείτε μηνύματα, να ξαναγράψετε/διαγράψετε/αναταξινομήσετε commits, κλπ.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Χρησιμοποιήστε την για να καθαρίσετε commits εύκολα και χωρίς να χρειαστεί ένα πιο πολύπλοκο rebase.
[Αυτό το άρθρο](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) περιέχει πολύ καλά παραδείγματα σχετικλα με το πώς και πότε να το κάνετε.
### cherry-pick
Είναι πολύ χρήσιμη για να εφαρμόσετε το commit που κάνατε στο λάθος κλαδί, χωρίς την ανάγκη να ξαναγράψετε τον κώδικα.
Παράδειγμα:
```
$ git cherry-pick 790ab21
[master 094d820] Φτιάξει ελληνική γραμματική στο "Συνεισφορά"
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Ας υποθέσουμε ότι έχουμε το ακόλουθο diff:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Μπορούμε να χρησιμοποιήσουμε `git add -p` για να προσθέσουμε μόνο τα patches που θέλουμε, χωρίς να χρειάζεται να αλλάξουμε τον κώδικα που έχει ήδη γραφτεί.
Είναι χρήσιμο να διαιρούμε μια μεγάλη αλλαγή σε μικρότερα commits ή να επαναφέρουμε/κάνουμε checkout συγκεκριμένες αλλαγές.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Άλλα ενδιαφέροντα πράγματα
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Σας άρεσε;
[Πείτε ευχαριστώ!](https://saythanks.io/to/RomuloOliveira)
## Συνεισφορά
Κάθε είδους βοήθειας θα ήταν καλοδεχούμενη. Παράδειγμα από θέματα με τα οποία μπορείτε να με βοηθήσετε:
- Διορθώσεις στην γραμματική και την ορθογραφία
- Μετάφραση σε άλλες γλώσσες
- Βελτίωση της αναφοράς πηγών
- Λανθασμένη ή ατελής πληροφορία
## Εμπνεύσεις, πηγές, και τι να διαβάσετε περαιτέρω
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_it-IT.md
================================================
# Guida per i messaggi di commit
[](https://saythanks.io/to/RomuloOliveira)
Una guida per capire l'importanza dei messaggi di commit e come scriverli bene.
Potrebbe aiutarti a capire cos'è un commit, perché è importante scrivere buoni messaggi, buone pratiche e alcuni consigli per pianificare e (ri)scrivere una buona storia per i commit.
## Cos'è un "commit"?
In termini semplici, un commit è una _fotografia_ dei file locali, scritti nel repository locale.
Contrariamente a cosa pensano alcune persone, [git non memorizza solo le differenze tra i file, ma la versione completa di tutti i file](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
Per i file che non cambiano tra un commit e l'altro, git memorizza solo un link al file identico precedente che è già memorizzato.
L'immagine qui sotto mostra come git memorizza i dati nel tempo, nella quale ogni "Version" è un commit:
## Perché i messaggi di commit sono importanti??
- Per velocizzare e snellire la _code review_ (revisione del codice)
- Per aiutare la comprensione di un cambiamento
- Per spiegare i motivi del cambiamento, che non possono essere spiegati con il solo codice
- Per aiutare i _maintainers_ futuri a capire perché e come i cambiamenti sono stati fatti, rendendo la futura individuazione e risoluzione di problemi più facile
Per massimizzare questi risultati, possiamo usare alcune buone pratiche e standard descritti nella prossima sezione.
## Buone pratiche
Queste sono alcune (buone) pratiche collezionate dalla mia esperienza, da articoli su internet, e altre guide. Se ne avete altre (o non siete d'accordo su alcune) sentitevi liberi di aprire una Pull Request e contribuire.
### Uso della forma imperativa
```
# Corretto
Usa InventoryBackendPool per recuperare il backend dell'inventario
```
```
# Errato
Usato InventoryBackendPool per recuperare il backend dell'inventario
```
_Ma perché usare la forma imperativa?_
Un messaggio di commit descrive cosa fa il cambiamento (a cui fa riferimento), i suoi effetti,, non cosa è stato fatto.
### La prima lettera in maiuscolo
```
# Corretto
Aggiunge il metodo `use` al modello Credit
```
```
# Errato
aggiunge il metodo `use` al modello Credit
```
Il motivo per mettere la prima lettera iniziale è per seguire le regole grammaticali che impongono la lettera maiuscola ad inizio di una frase.
L'uso di questa pratica può variare da persona a persona, gruppo a gruppo, o anche da lingua a lingua. In maiuscolo o no, l'importante è usare un solo standard e seguirlo.
### Tenta di comunicare cosa il cambiamento fa senza la necessità di guardare il codice
```
# Corretto
Aggiunge il metodo `use` al modello Credit
```
```
# Errato
Aggiunge il metodo `use`
```
```
# Corretto
Incrementa il padding sinistro tra il textbox e
layout frame
```
```
# Errato
Sistema il CSS
```
E' utile in tanti scenari (esempio: commit multipli, parecchi cambiamenti e ristrutturazioni) per aiutare i revisori a capire cosa il _committer_ (ovvero chi ha fatto il commit) stava pensando.
### Usa il corpo del messaggio per spiegare "perché", "per cosa", "come" e dettagli aggiuntivi
```
# Corretto
Corregge il nome del metodo delle classi figlie
di InventoryBackend
Classi derivate da InventoryBackend non rispettavano la classe base.
Funzionava perché il carrello chiamava l'implementazione di backend non
corretta.
```
```
# Corretto
Serializza e deserializza i crediti in JSON in
Cart
Converte le istanze di Credit in dizionario per due motivi:
- Pickle si basa sul percorso del file per le classi e non vogliamo
rompere tutto se ci sarà una ristrutturazione
- Dizionari e tipi built-in sono pickleable by default
```
```
# Corretto
Aggiunge il metodo `use` a Credit
Cambia da namedtuple a classe perché abbiamo bisogno di preparare un
nuovo attributo (in_use_amount) con un nuovo valore
```
L'oggetto ed il corpo del commit sono separati da una linea vuota.
Linee vuote aggiuntive sono considerate parte del messaggio.
Caratteri come `-`, `*` e \` sono elementi che aiutano la leggibilità.
### Evita messaggi di errore generici o messaggi senza contesto
```
# Errati
Correggi questo
Corrette delle cose
Ora dovrebbe funzionare
Cambia delle cose
Aggiusta il css
```
### Limita il numero di colonne
[E' consigliato](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) usare al massimo 50 caratteri per l'oggetto e 72 per il corpo di ogni commit.
### Mantieni la lingua in modo consistente
Per i proprietari dei progetti: scegli una lingua e scrivi tutti i messaggi di commit in quella lingua. Sarebbe l'ideale se fosse la stessa lingua con cui si scrivono i commenti nel codice, la stessa predefinita per l'applicazione, ecc.
Per chi collabora: scrivi i messaggi dei tuoi commit rispettando la stessa lingua della history dei commit.
```
# Corretto
ababab Aggiunge il metodo `use` al modello Credit
efefef Usa InventoryBackendPool per recuperare il backend dell'inventario
bebebe Correggi il nome del metodo delle classi figlio di InventoryBackend
```
```
# Corretto (esempio in Portuguese)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Errato (mischia English e Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Modelli
Questo è un modello, [scritto originariamente da Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), che appare in [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Raccogli i cambiamenti in 50 caratteri o meno
Una spiegazione più dettagliata se necessario. Vai a capo a circa 72
caratteri. In alcuni contesti, la prima linea è trattata come oggetto
del commit, ed il resto come il corpo. La linea vuota che separa
l'oggetto dal corpo è necessaria (amenoché il corpo non sia vuoto);
vari strumenti come `log`, `shortlog` e `rebase` possono confondersi se
li metti insieme.
Spiega il problema che questo commit risolve. Focalizzati sul perché
stai facendo questo cambiamento al contrario di come (il codice lo
spiega già di suo). Ci sono side-effects o altre conseguenze non
intuitive a seguito di questo cambiamento? Questo è il posto per
spiegarle.
Altri paragrafi vengono dopo linee vuote.
- Elenchi puntati vanno bene
- Di solito un trattino o un asterisco son usati per il punto,
preceduti da un singolo spazio, con linee vuote nel mezzo, ma qui le
convenzioni variano
Se hai un sistema di tracciamento delle issues, puoi mettere i
riferimenti alla fine, così:
Risolve: #123
Vedi anche: #456, #789
```
## Rebase vs. Merge
Questa sezione è un **TL;DR** degli eccellenti tutorial di Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase
**TL;DR:** Applica i commit del tuo branch, uno a uno, al branch di base, generato un nuovo albero.
### Merge
**TL;DR:** Crea un nuovo commit, chiamato (propriamente) _merge commit_, con le differenze tra i due branches.
### Perché qualcuno preferisce "rebase" a "merge"?
Anche io, tra i tanti, preferisco "rebase" a "merge". Le motivazioni sono, tra le altre:
* Genera una history "pulita", senza _merge commits_ non necessari
* _What you see is what you get_, ovvero in una revisione del codice tutti i cambiamenti arrivano da uno specifico commit, evitando cambiamenti nascosti nei _merge commits_
* Più merges sono risolti da chi crea il commit, e ogni cambiamento in un merge è un commit con un proprio messaggio
* E' poco comune guardare e revisionare i commit di merge, quindi evitarli del tutto assicura che tutti i cambiamenti sono sotto il commit dove dovrebbero essere
### Quando fare lo "squash"
"Squashing" (o _fare squash_) è il processo di prendere diversi commit e condensarli all'interno di un singolo unico commmit.
E' utile quando, ad esempio, si vuole:
- Ridurre i commit con poco o nulla (correzioni di errori ortografici o simili, formattazione, cose dimenticate)
- Unire cambiamenti sperati che hanno più senso applicati insieme
- Riscrivere un commit che era _work in progress_
### Quando evitare "rebase" o "squash"?
Evita "rebase" e "squash" in commit pubblici, oppure in branch condivisi dove più persone stanno lavorando.
"Rebase" e "squash" riscrivono la storia e sovrascrivono i commit esistenti: fare questo in commit che sono in branch condivisi (ovvero, sincronizzati con repository remoti) può causare confusione, e le persone potrebbero perdere il proprio lavoro (locale o remoto) a causa di alberature divergenti e conflitti.
## Comandi git utili
### rebase -i
Usa per fare uno "squash", modificare messaggi, riscrivere/eliminare/riordinare i commit, etc.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Usa per pulire i commit in modo semplice e senza un rebase "complesso".
[Questo articolo](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) ha dei buoni esempi su come e quando fare ciò.
### cherry-pick
E' utile per applicare un commit fatto in un altro branch (anche per errore), senza aver bisogno di riscriverlo.
Esempio:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Facciamo il caso di avere il seguente _diff_:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Possiamo usare `git add -p` per aggiungere solo le patch che vogliamo, senza aver bisogno di cambiare il codice che è già scritto.
E' utile per spezzare grandi cambiamenti in piccoli commit, o per fare il reset/checkout di cambiamenti specifici.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Altre cose interessanti
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Ti piace?
[Ringrazia!](https://saythanks.io/to/RomuloOliveira)
## Contribuire
Qualsiasi tipo di aiuto è apprezzato. Un esempio di cose per cui potete aiutarmi sono:
- Correzioni grammaticali e ortografiche
- Traduzione in altre lingue
- Miglioramento nei riferimenti alle sorgenti
- Informazioni parziali o incomplete
## Fonti d'ispirazione, sorgenti e altre letture
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_ja-JP.md
================================================
# コミットメッセージガイド
[](https://saythanks.io/to/RomuloOliveira)
コミットメッセージの重要性と良いコミットメッセージの書き方を理解するためのガイドです
(訳注: 本日本語訳では、英語でコミットメッセージを書くことを想定します)
コミットとは何か、良いコミットメッセージを書くことが重要であるのはなぜか、良いコミット履歴を計画し書く(書き直す)ための最良の方法とコツを学ぶのを手助けできるかもしれません。
## 「コミット」とは何か?
簡単に言うと、コミットとはあなたのローカルリポジトリーに書かれたローカルファイルの _スナップショット_ です。
人々が考えているのとは異なり、[gitはファイルの差分のみを保持しているのではなく全てのファイルの全てのバージョンのファイルそのものを保持しています](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences)。
1つのコミットで以前と変更がないファイルについては、gitは既に保持している以前のバージョンの同一ファイルへのリンクを保持します。
下図は、gitが経時的にデータをどのように保持しているかを示しています。個々の「version」をコミットだと考えてください。
## なぜコミットメッセージは重要なのか?
- 素早く効率的にコードレビューをするため
- 変更を理解するのを助けるため
- コードのみでは説明できない「なぜ」を説明するため
- 未来のメンテナーが、なぜどのように変更がされたのかを理解し、トラブル解決とデバッグを容易にできるようにするため
これらの成果を最大化するために、次のセクションで説明する良い事例と標準を使うことができます。
## 良い事例
私の経験やインターネット上の記事、他のガイドから集めた良い事例があります。
他に良い事例を知っていたり、賛成できないものがある場合には、気軽にプルリクエストを送って貢献してください。
### 命令形を使う
```
# 良い例
Use InventoryBackendPool to retrieve inventory backend
```
```
# 悪い例
Used InventoryBackendPool to retrieve inventory backend
```
_しかし、なぜ命令法を使うべきなのでしょうか?_
コミットメッセージは、関連付けられる変更が実際に何を*する*のか、どんな効果を持つのかを説明するものであり、何がされたのかを説明するものではありません。
### 最初の文字を大文字にする
```
# 良い例
Add `use` method to Credit model
```
```
# 悪い例
add `use` method to Credit model
```
最初の文字を大文字にするのは、文の初めの文字は大文字にするという文法規則に従っています。
これは人によりチームにより言語により異なります。
大文字にするにしてもしないにしても、重要なのは1つの標準にこだわり従うことです。
### ソースコードを見ることなく変更を伝えられるようにする
```
# 良い例
Add `use` method to Credit model
```
```
# 悪い例
Add `use` method
```
```
# 良い例
Increase left padding between textbox and layout frame
```
```
# 悪い例
Adjust css
```
このことは、多くのシナリオ(例えば、複数のコミットやいくつかの変更、リファクタリング)で、コミッターが考えていたことをレビュアーが理解するのを助けます。
### 「なぜ」「何のために」「どのように」その他の詳細を説明するためにメッセージの本文を使う。
```
# 良い例
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# 良い例
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# 良い例
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
メッセージの件名と本文は空行で区切ります。それ以上の空行はメッセージの本文の一部とみなされます。
`-`や`*`、\`といった文字は読みやすくするために使えます。
### 一般的なメッセージや文脈の分からないメッセージを避ける
```
# 悪い例
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### 文字数を制限する
件名は50文字、本文は1行につき72文字を上限とするのが[推奨されています](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)。
### 言語の一貫性を保つ
プロジェクトのオーナーへ: 言語を1つ選び、全てのコミットメッセージにその言語を使ってください。
その言語がコード中のコメントやデフォルトの翻訳ロケール(ローカライズされたプロジェクトの場合)などとも一致している方が良いです。
貢献者へ: 既に存在するコミット履歴の言語を使ってあなたのコミットメッセージを書いてください。
```
# 良い例
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# 良い例 (ポルトガル語の例)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# 悪い例 (英語とポルトガル語が混在している)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### テンプレート
これは[元々Tim Popeによって書かれた](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)テンプレートで、[_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)に収録されています。
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## リベース対マージ
このセクションは、Atlassianの優れたチュートリアルである["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)をまとめたものです。
### リベース
**まとめ**: あなたのブランチのコミットを1つ1つベースのブランチに追加して、新しいツリーを生成します。
### マージ
**まとめ**: 適切には _マージコミット_ と呼ばれる、2つのブランチの間の差分である新しいコミットを作成します。
### なぜマージよりリベースを好む人々がいるのか?
私は特にマージよりリベースの方が良いと考えています。理由は以下の通りです。
* リベースは「クリーン」な履歴を生成し、不必要なマージコミットを生成しない
* 見たままが得られる、つまり、コードレビューで全ての変更が特定のコミットと関連付けられ、マージコミットに変更が隠れるのを防げる
* コミッターによりマージがされるにつれて、それぞれのマージの変更は適切なメッセージを持った1つのコミットにまとまってしまう
* マージコミットを掘り起こしたり、レビューしたりすることは通常やるべきことではない。それを避けるために、全ての変更はそれぞれのコミットを持つようにする
### スカッシュすべき時
「スカッシュ」とは、一連のコミットを1つのコミットまとめるプロセスです。
これは、以下の例のような状況では一般的です。
- 文脈が乏しいまたはないコミットをなくす (誤字を訂正する、フォーマットを整える、忘れていたものを含める)
- 一緒に適用された方がより意味が明確になる分かれた変更をまとめる
- _作業中_ のコミットを書き直す
### リベースやスカッシュを避けるべき時は?
リベースやスカッシュは、公開されたコミットまたは複数の人が作業している共有されたブランチでは避けてください。
リベースやスカッシュは履歴を書き換え、既存のコミットを上書きします。
これを共有されたブランチで行うと混乱をまねき(つまり、コミットはリモートリポジトリーにプッシュされるし、リモートリポジトリーは他の人のブランチから生成される)、ツリーの状態が一貫性を失い競合が発生することで、他の人が自分の変更を(ローカルとリモートの両方で)失うかもしれません。
## 有用なgitコマンド
### rebase -i
コミットをスカッシュしたり、メッセージを編集したり、コミットを書き換えたり、削除したり、並べ替えたりするために使います。
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
もっと複雑なリベースを必要とせず、簡単にコミットを綺麗にするために使います。
[この記事](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)はどのように、どういう時に使うべきかのとても良い例を示しています。
### cherry-pick
間違って別のブランチでしてしまったコミットをコードを書き直すことなく適用させるのにとても便利です。
例:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
以下のような差分があるとします。
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
`git add -p`を使うことで、必要なパッチのみ追加することができ、既に書かれたコードを変更する必要はありません。
これは大きな変更をより小さなコミットに分割するのに役立ちますし、特定の変更をreset/checkoutするのにも役立ちます。
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### 部分1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### 部分2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### 部分3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## その他の有用なこと
https://whatthecommit.com/
## 気に入りましたか?
[ありがとう!を言う](https://saythanks.io/to/RomuloOliveira)
## 貢献する
どんな種類の手助けも歓迎します。例えば以下の事項で手助けしてください。
- 文法と綴りの訂正
- 他の言語への翻訳
- 他の情報源への参照の改善
- 間違っていたり不完全であったりする情報の訂正
## インスピレーションや情報源、次に読むべきもの
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_ko-KR.md
================================================
# 커밋 메시지 가이드
[](https://saythanks.io/to/RomuloOliveira)
커밋 메시지의 중요성을 이해하고 어떻게 하면 잘 작성할 수 있는지에 대해 설명하는 안내서입니다.
커밋 메시지가 무엇이며, 왜 잘 작성하는 것이 중요한지 알아보고 좋은 커밋 히스토리를 유지하고 싶을 때 적용할 수 있는 최고의 접근법과 몇 가지 유용한 팁을 배워봅시다.
## "commit" 이 무엇인가요?
간단히 말해서, "커밋 (commit)" 은 로컬 저장소에 쓰여지는 로컬 파일들의 단편본입니다.
일반적으로 사람들이 생각하는 것과는 다르게, [git은 파일의 변경된 내용만을 기록하지 않고 모든 파일의 버전을 모두 기록합니다](https://git-scm.com/book/ko/v2/%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0-Git-%EA%B8%B0%EC%B4%88#_%EC%B0%A8%EC%9D%B4%EA%B0%80_%EC%95%84%EB%8B%88%EB%9D%BC_%EC%8A%A4%EB%83%85%EC%83%B7).
어떤 한 커밋과 다른 커밋 사이에 변경된 내용이 없다면, git은 이미 동일한 파일에 대해 링크만 생성합니다.
아래의 이미지는 시간이 지남에 따라 git이 어떻게 데이터를 저장하는지 보여줍니다. 각 "Version" 은 커밋을 뜻합니다.
## 왜 커밋 메시지가 중요한가요?
- 코드 리뷰 시간을 단축하고 능률적으로 처리하기 위해서
- 변경 사항을 이해하는데 도움을 주기 위해서
- 코드만으론 설명이 어려운 "왜 이렇게 했을까" 를 설명하기 위해서
- 추후 작업할 사람이 왜/어떻게 변경 사항이 만들어졌는지 이해하는데 도움을 주고 문제 해결과 디버깅을 쉽게 만들기 위해서
이로부터 얻는 이로운 효과를 극대화 하기 위해, 활용할 수 있는 좋은 습관과 표준을 다음 섹션에서 설명합니다.
## 좋은 습관
다음 설명할 습관들은 제 개인적인 경험, 인터넷 글, 다른 가이드에서 얻어온 것입니다. 더 추가할 내용(또는 뺄 내용)이 있다면 Pull Request 를 열고 기여해주세요.
### 명령조 사용하기
```
# 좋음
InventoryBackendPool을 사용하여 재고 백엔드를 검색합니다
---
Use InventoryBackendPool to retrieve inventory backend
```
```
# 나쁨
InventoryBackendPool을 사용하여 재고 백엔드를 검색했습니다
---
Used InventoryBackendPool to retrieve inventory backend
```
_근데 왜 명령조를 쓰나요?_
커밋 메시지는 무엇이 변경되었는지가 아니라 실제로 그 변경 사항이 미치는 영향, 즉 변경 사항이 실질적으로 무엇을 하는지 설명합니다.
### 첫 번째 문자를 대문자로 시작하기
```
# 좋음
Add `use` method to Credit model
```
```
# 나쁨
add `use` method to Credit model
```
첫 문자를 대문자로 작성해야 하는 이유는 문장의 시작 부분에 대문자를 사용하는 문법 규칙을 따르기 위함입니다.
이런 실질적인 규칙의 사용상은 사람, 팀, 언어마다 다를 수 있습니다.
대문자로 시작하건 아니건, 중요한 것은 하나의 표준을 만들어 계속 따르는 것입니다.
_역주:_ 한국어는 크게 영향이 없을 듯 합니다.
### 소스코드를 보지 않고도 변경 사항이 무엇을 하는지 알 수 있도록 하기
```
# 좋음
Credit 모델에 `use` 메소드 추가
---
Add `use` method to Credit model
```
```
# 나쁨
`use` 메소드 추가
---
Add `use` method
```
```
# 좋음
텍스트 상자와 레이아웃 프레임 사이 왼쪽 간격 늘림
---
Increase left padding between textbox and layout frame
```
```
# 나쁨
CSS 조정
---
Adjust css
```
이는 다양한 상황 (e.g. 다중 커밋, 서로 다른 변경 사항, 리팩토링)에서 코드 리뷰를 진행하는 사람이 커밋 작성자가 무슨 생각을 하고 있었는지 쉽게 이해할 수 있도록 도움을 줄 수 있습니다.
### 커밋 메시지 본문으로 "왜", "무엇을 위해", "어떻게" 변경했는지와 상세 내용 추가 설명하기
```
# 좋음
InventoryBackend 자식 클래스의 메소드 이름 수정
InventoryBackend를 상속받는 클래스가 기반 클래스의 인터페이스를 따르지 않음.
Cart가 잘못된 방식으로 백엔드 구현을 호출하고 있었기 때문에 문제가 없었음.
---
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# 좋음
Credits을 cart의 json에 직렬화 및 역직렬화합니다
Credit 객체를 딕셔너리로 전환하는데 두 가지 이유가 있습니다:
- Pickle이 클래스의 파일 경로에 의존하기 때문에 리팩토링시 로직이 망가질 수 있습니다
- 딕셔너리와 빌트인 타입은 기본적으로 pickle 모듈에 의해 직렬화가 가능합니다
---
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# 좋음
Credit에 `use` 메소드 추가
새 속성(in_use_amount)값이 필요하기 때문에 namedtuple에서 클래스로 전환했습니다
---
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
제목과 메시지 본문은 공백 행 하나로 분리합니다.
이후 추가되는 공백은 메시지 본문의 일부로 취급합니다.
`-`, `*`, \` 와 같은 문자를 사용하면 가독성을 향상시킬 수 있습니다.
### 맥락 없는 총칭적 메시지 사용 자제하기
```
# 나쁨
이거 고침
뭔가 고침
이제 잘 작동할거임
뭔가 변경함
CSS 조정
---
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### 행 글자 수 제한하기
제목은 50자, 본문은 72자로 한 줄에 들어갈 수 있는 글자 수를 제한하는 것이 [권장됩니다](https://git-scm.com/book/ko/v2/%EB%B6%84%EC%82%B0-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C%EC%9D%98-Git-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-%EA%B8%B0%EC%97%AC%ED%95%98%EA%B8%B0#_commit_guidelines).
### 일정한 언어 사용하기
프로젝트 소유자인 경우: 언어 하나를 선택해서 모든 커밋을 그 언어만 사용해서 작성합니다. 궁극적으로, 이 규칙은 코드 주석과 기본 언어 파일 (다국어 지원 프로젝트의 경우) 등 모두 일치해야 합니다.
기여자의 경우: 이미 커밋 히스토리에서 사용되고 있는 언어를 사용하여 커밋 메시지를 작성합니다.
```
# 좋음
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# 좋음 (한국어 예시)
ababab Credit 모델에 `use` 메소드 추가
efefef InventoryBackendPool을 사용하여 재고 백엔드를 검색합니다
bebebe InventoryBackend 자식 클래스의 메소드 이름 수정
```
```
# 나쁨 (영어와 한국어 혼용)
ababab Credit 모델에 `use` 메소드 추가
efefef Use InventoryBackendPool to retrieve inventory backend
cdcdcd 이제 잘 작동할거임
```
### 템플릿
이 템플릿은 [_Pro Git Book_](https://git-scm.com/book/ko/v2/%EB%B6%84%EC%82%B0-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C%EC%9D%98-Git-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-%EA%B8%B0%EC%97%AC%ED%95%98%EA%B8%B0)에 나와있는 [Tim Pope의 커밋 메시지](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)를 발췌한 것입니다.
```
여기에 최대 50자까지 변경 사항에 대해 설명하세요
필요하다면 여기에 좀 더 상세하게 설명하세요. 한 줄당 대략 72자까지 맞출 수 있도록
합니다. 일부 상황에서 첫 줄은 커밋의 제목이 되고, 그 후에 작성되는 텍스트는 본문으로
취급됩니다. 제목과 본문을 나누는 중간에 삽입되는 공백 행은 매우 중요합니다 (본문을
완전히 생략하지 않는 이상); `log` 와 `shortlog`, `rebase` 와 같이 다양한
도구들은 공백에 의존하므로 두 부분을 합쳐버릴 경우 도구가 혼동할 수 있습니다.
이 커밋이 해결하고자하는 문제를 설명합니다. 어떻게 했는지보단(코드가 설명할 것이기 때문),
왜 변경 사항을 적용했는지에 대해 집중합니다. 이 변경 사항으로 인해 생기는 부수 효과가
있거나 다른 직관적이지 않은 영향이 있을 수 있다면 여기에 설명하세요.
앞으로 추가되는 문단은 공백 행 뒤에 옵니다.
- 필요하다면 강조점을 써도 됩니다
- 하이픈(-) 또는 별(*)이 주로 강조점으로 사용되고 이후 단일 공백(space)을 삽입합니다
강조점 사이에는 공백 행을 넣지만 규칙은 언제든지 바꿀 수 있습니다
이슈 트래커를 사용한다면 다음과 같이 레퍼런스를 메시지 하단에 삽입하세요:
이슈: #123
같이보기: #456, #789
---
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
## 재정렬 (Rebase) vs. 병합 (Merge)
이 섹션은 Atlassian의 멋진 튜토리얼 ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 의 **길어서 안 읽음 요약 좀 (TL;DR)** 버전입니다.
### 재정렬 (Rebase)
**한 줄 요약:** 기반 브랜치부터 작업 브랜치의 커밋을 하나씩 차곡차곡 이어붙여 새로운 트리를 만듭니다.
### 병합 (Merge)
**한 줄 요약:** 두 브랜치의 변경 사항을 하나로 합쳐 (적절히) _병합된 커밋_ 이라 적힌 하나의 새 커밋을 만듭니다.
### 왜 사람들은 병합(merge)보다 재정렬(rebase)을 선호하나요?
다음과 같은 이유 때문에 저도 병합보단 재정렬을 선호합니다:
- 불필요한 병합된 커밋 없이 "깔끔한" 기록을 생성합니다
- _보이는 그대로 알 수 있습니다_, 특히, 코드 리뷰에서 커밋의 변경 사항을 병합된 커밋으로 인해 감춰지지 않고 모두 볼 수 있습니다
- 커미터(committer)가 더 직접적으로 병합에 관여하게 되고, 모든 병합 변경 사항이 적절한 커밋 메시지로 대체됩니다
- 병합 커밋을 리뷰하고 파고드는 일은 드묾으로, 병합을 피하면 모든 변경 사항이 각자 적절한 커밋에 연관되도록 할 수 있습니다.
### 스쿼시(squash)가 필요할 때
"스쿼싱 (Squashing)" 은 일련의 커밋을 받아서 하나의 커밋으로 간략화시키는 작업입니다.
다음과 같은 상황에 유용할 수 있습니다:
- 맥락이 없거나 너무 작은 커밋들 줄이기 (오타 교정, 코드 정리, 잊어버린 부분 추가)
- 하나로 합쳤을 때 더 의미가 있는 변경 사항들
- _현재 작업 중 (work in progress)_ 커밋 재작성
### 어떨 때 재정렬(rebase), 스쿼시(squash)의 사용을 피해야 하나요?
재정렬과 스쿼시 모두 공개된 커밋이나 많은 사람들이 같이 작업하는 공유된 브랜치에선 사용하지 않는 것이 좋습니다.
재정렬과 스쿼시는 기존 커밋 기록을 다시 작성해서 덮어씌우기 때문에 위에서 언급한 공유된 브랜치(주로, remote로 푸시 된 커밋 또는 다른 브랜치로부터 받은 커밋)에 적용하게 되면 혼란을 빛게되고 분기 트리와 충돌로 인해 다른 사람들이 작업한 변경 사항을 잃을 수도 있습니다(local과 remote 모두).
## 유용한 git 커맨드
### rebase -i
커밋을 스쿼시가 필요할때, 메시지를 변경하거나, 커밋 재작성/삭제/순서 변경이 필요할 때 사용하세요.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
복잡한 재정렬을 할 필요 없이 쉽게 커밋을 정리할 때 사용하세요. [이 글](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)에서 언제 어떻게 사용해야 하는지 좋은 예시로 설명하고 있습니다.
### cherry-pick
실수로 엉뚱한 브랜치에 커밋을 했을 때 다시 작업할 필요 없이 해당 커밋을 다른 브랜치에 적용시키고 싶을 때 사용하세요.
사용 예시:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
다음과 같은 diff가 있다고 가정해 봅시다:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
`git add -p` 를 사용하면 코드를 건드리지 않고 원하는 부분만 선택하여 스테이지에 추가할 수 있습니다.
큰 변경 사항을 작은 커밋으로 쪼개거나 특정 변경 사항을 reset/checkout 할 때 유용하게 사용할 수 있습니다.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## 다른 흥미로운 것들
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## 맘에 들어요?
[고마웡!](https://saythanks.io/to/RomuloOliveira)
## 기여하기
형식에 상관없이 도움을 주시면 감사하겠습니다. 다음과 같은 주제가 있습니다:
- 문법 또는 철자 교정
- 다른 언어로 번역
- 출처 참조 개선
- 잘못되었거나 완전하지 않은 정보 개선
## 영감, 출처, 더 읽어보기
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_pl-PL.md
================================================
# Przewodnik po commitach
[](https://saythanks.io/to/RomuloOliveira)
Przewodnik ten, pomoże Ci zrozumieć jak ważne są wiadomości zawierane w commitach i jak je dobrze pisać.
Dodatkowo pomoże Ci zrozumieć czym są same commity, jak ważne jest pisanie dobrych wiadomości, jakie są najlepsze praktyki i wskazówki, do pisania (i poprawienia) naprawdę dobrej historii commitów.
Na potrzeby przewodnika, będziemy używać słowa "commit" - zamiast polskich odpowiedników "popełnić, angażować, oddać, zatwierdzić"
A na wiadomości do commitów (strasznie to brzmi po Polsku) będziemy pisać "commit message"
## Dostępne języki
- [English](README.md)
- [Português](README_pt-BR.md)
- [Deutsch](README_de-DE.md)
- [Español](README_es-AR.md)
- [Italiano](README_it-IT.md)
- [한국어](README_ko-KR.md)
- [Русский](README_ru-RU.md)
- [简体中文](README_zh-CN.md)
- [日本語](README_ja-JP.md)
- [Українська](README_ua-UA.md)
- [Türkçe](README_tr-TR.md)
- [ngôn ngữ tiếng Việt](README_vi-VN.md)
- [繁體中文](README_zh-TW.md)
- [ελληνικά](README_gr-GR.md)
- [Française](README_fr-FR.md)
- [پارسی](README_fa-IR.md)
- [Polish](README_pl-PL.md)
## Co to jest "commit"?
W krótkich słowach, commit to _snapshot_ _(migawka)_ Twoich lokalnych plików, zapisana w Twoim lokalnym repozytorium. Czyli ich dokładna kopia.
W przeciwieństwie do tego, co myślą niektórzy, [git nie przechowuje tylko i wyłącznie róznic między plikami, przechowuje pełną warsj wszystkich plików](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).
Jeżeli któryś plik nie zmienił się między commitami, to git "linkuje" go, po to, by oszczędzić miejsce.
Obrazek poniżej, pokazuje jak git przechowuje dane, każda wersja, to commit:
## Dlaczego commit messages są ważne?
- Aby przyspieszyć i usprawnić code-reviews (analize i ocenianie kodu przez innych programistów)
- Aby pomóc w zrozumieniu zmiany danego commita
- Aby wyjaśnić „dlaczego” zrobiliśmy coś, ponieważ nie zawsze da się to opisać kodem
- Aby pomóc przyszłym programistom dowiedzieć się, dlaczego i jak dokonano zmian, ułatwiając rozwiązywanie problemów i debugowanie.
Aby zmaksymalizować te punkty, możemy skorzystać z dobrych praktyk i standardów opisanych w następnym rozdziale.
## Dobre praktyki
Oto niektóre praktyki zebrane z moich doświadczeń, artykułów internetowych i innych przewodników. Jeśli masz inne (lub nie zgadzasz się z niektórymi), możesz otworzyć Pull Request i wnieść swój wkład.
Jako że commit messages, piszemy w języku angielskim, nie będą one tłumaczone.
### Użyj trybu rozkazującego
```
# Dobrze
Use InventoryBackendPool to retrieve inventory backend
```
```
# Żle
Used InventoryBackendPool to retrieve inventory backend
```
_Ale po co używać trybu rozkazującego?_
commit message opisuje co zmiana aktualnie **robi**. Chodzi o zmiany w kodzie, a nie o to co zostało zrobione.
### Zacznij z dużej litery
```
# Dobrze
Add `use` method to Credit model
```
```
# Żle
add `use` method to Credit model
```
Powodem, dla którego pierwsza litera powinna być wielka, jest przestrzeganie prostej zasady gramatycznej, polegającej na używaniu wielkich liter na początku zdania.
Stosowanie tej praktyki może różnić się w zależności od zespołu.
### Staraj się komunikować, co robi zmiana, bez konieczności patrzenia na kod źródłowy
```
# Dobrze
Add `use` method to Credit model
```
```
# Żle
Add `use` method
```
```
# Dobrze
Increase left padding between textbox and layout frame
```
```
# Żle
Adjust css
```
Pomoże Ci to w wielu przypadkach (np. wyszukiwanie danej zmiany w kilku commitach). Nie ma nic gorszego, niż szukanie odpowiedniego commita, wsród kilkunastu z opisem "visual fixes".
### Użyj ciała wiadomości, aby wyjaśnić „dlaczego”, „po co” i „jak”
```
# Dobrze
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
```
```
# Dobrze
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
```
```
# Dobrze
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
```
Głowa i ciało wiadomości są oddzielone pustą linią.
Znaki takie jak `-`, `*` i \` znacznie zwiększają czytelność.
### Unikaj ogólnych wiadomości lub wiadomości bez kontekstu
```
# Źle
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
```
### Ogranicz liczbę znaków
[Zalecane jest](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) używać tylko 50 znaków w temacie (głowie) i 72 w ciele.
### Zachowaj spójność językową
Do właścicieli projektów: wybierz język i pisz wszystkie commit messages w tym języku. Najlepiej by był to ten sam język, w którym znajdują się nazwy zmiennych, metod czy obiektów.
(Najczęściej jest to angielski, chyba że przyjdzie Wam pracować dla PKP)
Dla współtwórców: Pisz commit messages, używając tego samego języka, którego używali poprzedni commitujący.
```
# Dobrze
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
```
```
# Dobrze (Portuguese example)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
```
```
# Źle (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
```
### Szablon
Oto cytat, [napisany przez Tima Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), Ktory pojawia się w [_Wspaniałej książce o gicie_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```
PL:
```
Podsumuj zmiany w około 50 znakach lub mniej
W razie potrzeby bardziej szczegółowy tekst objaśniający zmieść w 72 znakach.
W niektórych commitach pierwsza linia jest traktowana jako
temat commitu, a reszta tekstu jako jego treść.
pusta linia oddzielająca głowę od ciała jest bardzo ważna (chyba że całkowicie pomijasz ciało);
Wyjaśnij problem, który rozwiązuje commit. Skoncentruj się na tym, dlaczego
wprowadzasz tę zmianę, a nie na tym jak (kod to wyjaśni).
Czy są jakieś błędy i problemy które tworzy ten commit?
W ciele commitu możesz je wyjaśnić.
Kolejne akapity pojawiają się po pustych wierszach.
- punktory też są w porządku
- Zazwyczaj przed punktorem stosuje się myślnik lub gwiazdkę, poprzedzone spacją.
Jeśli korzystasz z narzędzia do śledzenia zgłoszeń, umieść odniesienia do nich na dole,
Na przykład:
Rozwiązuje: #123
Zobacz też: #456, #789
```
## Rebase vs. Merge (Zmiana bazy vs scalanie)
Ta sekcja to **TL;DR** (za długie do czytania) z wspaniałego samouczka Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
### Rebase (Zmiana bazy)
**TL;DR:** Układa Twoje gałęzie (branch) commitów, jeden po drugim, na gałęzi bazowej, generując nowe drzewo.
### Merge (Scalanie)
**TL;DR:** Tworzy nowy commit, nazwany (odpowiednio) _merge commit_, z informacjami o róznicach między gałęziami.
### Dlaczego niektórzy wolą zmienić bazę, zamiast scalić?
Ja wolę zmianę bazy. Powodami są:
- Generowanie „czystej” historii, bez zbędnych commitów scalających.
- _What you see is what you get_, (otrzymujesz to co widzisz), to znaczy wszystkie zmiany pochodzą z konkretnych i nazwanych commitów, unikamy zmian wprowadznych w merge commitach.
- Każdy commit jest z odpowiednią wiadomością, a my nie musimy potem kopać w zmianach, które wystąpiły przy scalaniu.
### Kiedy squashować
"Squashing" to proces zbierania serii commitów i kondensowaniu ich w jednym commicie. Czyli polega na "zgnieceniu" kilku commitów w jeden.
Przydaje się to w kilku sytuacjach, np.:
- Redukcja commitów z małą ilością zmian (formatowanie, literówki)
- Łączenie commitów, wprowadzających zmiany, które mają sens tylko jeżeli są razem.
- Nadpisywaniu niedokonczonych commitów.
### Kiedy unikać zmiany bazy lub squasha?
Unikaj zmiany bazy i squasha w publicznych zatwierdzeniach lub w gałęziach współdzielonych, nad którymi pracuje wiele osób.
Zmiana bazy i squash nadpisuję historię i istniejące commity, robienie tego na commitach, które znajdują się we współdzielonych gałęziach (tj. zatwierdzeń wypchniętych do zdalnego repozytorium lub pochodzących z innych gałęzi) może powodować zamieszanie i ludzie mogą utracić swoje zmiany (zarówno lokalnie, jak i zdalnie) z powodu rozbieżnych drzew i konfliktów.
## Przydatne komendy git
### rebase -i
Użyj go do squashowania commitów, edytowania wiadomości, przepisywania/usuwania/zmieniania kolejności zatwierdzeń itp.
```
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into the previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
#### fixup
Użyj go do łatwego czyszczenia commitówm bez potrzeby bardziej złożonej zmiany bazy.
[Ten artykuł](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) zawiera bardzo dobre przykłady, jak i kiedy to zrobić.
### cherry-pick
Bardzo przydatne jest zastosowanie tego commita, który wykonałeś w złej gałęzi, bez konieczności ponownego kodowania.
Przykładowo:
```
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
```
### add/checkout/reset [--patch | -p]
Powiedzmy, że mamy następującą różnicę:
```diff
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
Możemy użyć `git add -p` aby dodawać tylko te poprawki, które chcemy, bez konieczności zmiany kodu, który jest już napisany.
Przydatne jest podzielenie dużej zmiany na mniejsze commity, lub zresetowanie/pobranie określonych zmian.
```
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
```
#### hunk 1
```diff
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?
```
#### hunk 2
```diff
@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
```
#### hunk 3
```diff
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
```
## Więcej interesujących linków
- https://whatthecommit.com/
- https://gitmoji.carloscuesta.me/
## Spodobało Ci się?
[Say thanks!](https://saythanks.io/to/RomuloOliveira)
## Contributing
Wszelka pomoc jest mile widziana. Przykładowe tematy, w których możesz mi pomóc:
- Poprawki gramatyczne i ortograficzne
- Tłumaczenie na inne języki
- Poprawa odwoływania się do źródła
- Nieprawidłowe lub niepełne informacje
## Inspiracje, źródła i dalsze lektury
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
================================================
FILE: README_pt-BR.md
================================================
# Guia de mensagens de commit
[](https://saythanks.io/to/RomuloOliveira)
Um guia para entender a importância das mensagens de commit e como escrevê-las bem.
Pode te ajudar a aprender o que é um _commit_, entender porque é importante escrever boas mensagens usando boas práticas e conhecer dicas para planejar e (re)escrever o seu histórico de _commits_.
**Observações:** Apesar da versão em português ter sido escrita antes da versão em inglês, a versão inglês contém alguns textos que estão mais detalhados, assim como melhor referenciamento de fontes.
## O que é um "_commit_"?
Em termos simples, o **_commit_** é uma espécie de _snapshot_ dos seus arquivos locais gravado localmente no seu repositório. Ao contrário do que se pensa, o git *não* armazena apenas as diferenças e sim a cópia completa dos arquivos.
No caso de arquivos que não mudaram de um _commit_ para o outro, é gravada uma referência ao arquivo gerado no último snapshot.
A imagem abaixo mostra como o git armazena dados ao longo do tempo com uma versão para cada _commit_:
## Por que as mensagens são importantes?
- Facilita e agiliza o _code review_
- Ajuda no entendimento do que está acontecendo
- Explica os porquês ocultos que não podem ser explicados somente em código
- Facilita a solução de problemas e a depuração garantindo que futuros codificadores entendam por que e como as mudanças foram feitas
## Boas práticas
### Use o imperativo
```
# Good
Use InventoryBackendPool to retrieve inventory backend
```
```
# Bad
Used InventoryBackendPool to retrieve inventory backend
```
Por que!?
A mensagem de _commit_ diz o que ele **faz**, não o que foi feito.
### Primeira letra em maiúsculo
```
# Good
Add `use` method to Credit model
```
```
# Bad
add `use` method to Credit model
```
É uma regra bem discutível e a menos importante pra mim.
O motivo de escolher começar com letra maiúscula é simplesmente porque é assim
que se começa uma frase em qualquer texto.
### Tente comunicar o que o _commit_ faz sem que seja necessário olhar o conteúdo do _commit_
```
# Good
Add `use` method to Credit model
```
```
# Bad
Add `use` method
```
```
# Good
Increase left padding between textbox and layout frame
```
```
# Bad
Adjust css
```
### Use o corpo da mensagem para explicar "porquê", "para quê", "como" e detalhes adicionais
```
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because cart was calling the backend implementation
incorrectly.
```
```
# Good
Serialize and deserialize cr
gitextract_c26l5f1i/ ├── CODEOWNERS ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── README_az-AZ.MD ├── README_de-DE.md ├── README_es-AR.md ├── README_fa-IR.md ├── README_fr-FR.md ├── README_gr-GR.md ├── README_it-IT.md ├── README_ja-JP.md ├── README_ko-KR.md ├── README_pl-PL.md ├── README_pt-BR.md ├── README_ru-RU.md ├── README_tr-TR.md ├── README_ua-UA.md ├── README_vi-VN.md ├── README_zh-CN.md └── README_zh-TW.md
Condensed preview — 21 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (300K chars).
[
{
"path": "CODEOWNERS",
"chars": 67,
"preview": "* @RomuloOliveira\nREADME_de-DE.md @Ana06\nREADME_ua-UA.md @CODER591\n"
},
{
"path": "CONTRIBUTING.md",
"chars": 4900,
"preview": "# Contributing\n\nFirst of all, thanks for the taking time to contribute and help people!\n\nThis document contains a set of"
},
{
"path": "LICENSE",
"chars": 18646,
"preview": "Attribution 4.0 International\n\n=======================================================================\n\nCreative Commons"
},
{
"path": "README.md",
"chars": 19241,
"preview": "# Commit messages guide\n\n[](https://saythanks.io/t"
},
{
"path": "README_az-AZ.MD",
"chars": 20423,
"preview": "# Commit mesajları təlimatı\n\n[](https://saythanks."
},
{
"path": "README_de-DE.md",
"chars": 15604,
"preview": "# Commit Messages Guide\n\n[](https://saythanks.io/to"
},
{
"path": "README_es-AR.md",
"chars": 14656,
"preview": "# Guía de mensajes de commit\n\n[](https://saythanks"
},
{
"path": "README_fa-IR.md",
"chars": 14881,
"preview": "# راهنمای Commit-Message\n\n[](https://saythanks.io"
},
{
"path": "README_fr-FR.md",
"chars": 15362,
"preview": "# Guide sur les messages de commit\n\n[](https://sa"
},
{
"path": "README_gr-GR.md",
"chars": 16221,
"preview": "# Οδηγός για τα \"Μηνύματα Commit\"\n\n[](https:/"
},
{
"path": "README_it-IT.md",
"chars": 15017,
"preview": "# Guida per i messaggi di commit\n\n[](https://saytha"
},
{
"path": "README_ja-JP.md",
"chars": 11429,
"preview": "# コミットメッセージガイド\n\n[](https://saythanks.io/to/RomuloOl"
},
{
"path": "README_ko-KR.md",
"chars": 12893,
"preview": "# 커밋 메시지 가이드\n\n[](https://saythanks.io/to/RomuloOlivei"
},
{
"path": "README_pl-PL.md",
"chars": 16140,
"preview": "# Przewodnik po commitach\n\n[](https://saytha"
},
{
"path": "README_pt-BR.md",
"chars": 12929,
"preview": "# Guia de mensagens de commit\n\n[](https://sayth"
},
{
"path": "README_ru-RU.md",
"chars": 14822,
"preview": "# Руководство по написанию коммитов\n\n[](https:/"
},
{
"path": "README_tr-TR.md",
"chars": 14726,
"preview": "# Commit mesajları kılavuzu\n\n[](https://saythanks."
},
{
"path": "README_ua-UA.md",
"chars": 14718,
"preview": "# Керівництво по написанню комітів\n\n[](https://sa"
},
{
"path": "README_vi-VN.md",
"chars": 16892,
"preview": "# Hướng dẫn viết commit\n\n[](https://saythanks.io/t"
},
{
"path": "README_zh-CN.md",
"chars": 10264,
"preview": "# Commit messages guide\n\n[](https://saythanks.io/t"
},
{
"path": "README_zh-TW.md",
"chars": 10300,
"preview": "# Commit messages guide\n\n[](https://saythanks.io/t"
}
]
About this extraction
This page contains the full source code of the RomuloOliveira/commit-messages-guide GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 21 files (283.3 KB), approximately 85.4k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.