Add coffe

[hubacji1/oneflow.git] / intro.md

diff --git a/intro.md b/intro.md
index fb8dcd4c9355359971c1cd3638395c67ec325deb..56901f57cdf9b21ab98433d8f8ac6c90411a783d 100644 (file)
--- a/intro.md
+++ b/intro.md
@@ -1,6 +1,6 @@
 # Git is ...
 Source Code Management (SCM) and it's great. Check out https://git-scm.com/ for
-details.
+details. Maybe also https://githowto.com/ could be interesting.
 
 # Init - do it once per repository
 You may clone it like `git clone URL` or create one from a folder by `git
@@ -62,7 +62,7 @@ Use the change stored in history.
 git show COMMIT_ID
 ```
 
-# Changes - check out before commit
+# What is repository current state
 The status of the repository can be checked by `git status` command. This
 allows you to see *new files* that are not yet tracked, *changed files* whose
 changes are not yet ready to be commited to the log history and *changed files*
@@ -71,19 +71,83 @@ that are ready.
 The `git diff` command shows *changes* in not-yet-ready files and `git diff
 --cached` shows *changes* that are ready to be committed.
 
-# Commit - build repository history
-You get ready the files to be commited to the history by `git add FILE`
-command. If you change your mind, you may `git reset FILE` that file.
+## Command `git status`
+Show information about files in repository.
+```
+git status
+```
+
+There are 3 states for file changes (let's call them *patches*) before stored
+to git history: *untracked*, *unstaged*, and *staged*. Note that the whole file
+may be patch. Also, `git status` command does not show patches, but files
+containing these patches.
+
+*Untracked* means that patch was not stored by git yet.
+
+*Unstaged* files has older version stored in git history but patches are not
+ready to be stored in git history.
+
+*Staged* files has older version stored in git and patches will be stored to
+git history as soon as `git commit` command is used.
 
-If only huks of lines in file should be prepared for commiting to the history
-`git add -p FILE` and `git reset -p FILE` can be used respectively.
+## Command `git diff`
+The patches (file changes) may be shown by `git diff` command (because `git
+status` show files not patches).
 
-Before commiting to the history log check twice `git diff --cached` and `git
-diff`.
+Unstaged patches can be seen by:
+```
+git diff
+```
+
+And staged patches by:
+```
+git diff --cached
+```
+
+# Build repository history
+Use `git commit` to store staged patches to git history. Moving patches and
+files between states described above is done by `git add` and `git reset`
+commands.
+
+## Command `git add`
+To stage patches in file (it means to take untracked or unstaged patches and
+mark them as staged):
+```
+git add -p FILENAME
+```
+
+To stage all the patches in file use:
+```
+git add FILENAME
+```
+
+## Command `git reset`
+To remove patches from staged state (remove from staging area is also used):
+```
+git reset -p FILENAME
+```
 
-When sure that staged changes should be commited to the history, use `git
-commit -m'COMMIT MSG'`. For commit messages, some rules are good to keep in
-mind [1][]:
+Or again for all the patches in file:
+```
+git reset FILE
+```
+
+## Command `git commit`
+When sure that staged changes should be commited to the history, use:
+```
+git commit -m'COMMIT MSG'
+```
+
+Command without parameters will open text editor to let type the commit
+message.
+```
+git commit
+```
+
+Default text editor is `vim`. It can be closed by sequence `<Esc>:q!<Enter>`.
+
+Please, keep these [The seven rules of a great Git commit message][1] when
+writing the git commit messages:
 - Separate subject from body with a blank line.
 - Limit the subject line to 50 characters.
 - Capitalize the subject line.
@@ -92,6 +156,13 @@ mind [1][]:
 - Wrap the body at 72 characters.
 - Use the body to explain what and why vs. how.
 
+If still it's lot to remember, the heuristics is that a properly formed Git
+commit subject line should always be able to complete the following sentence:
+
+**If applied, this commit will your subject line here**
+
+[1]: https://chris.beams.io/posts/git-commit/
+
 # Cheat sheet
 Use `git COMMAND --help` for showing the help!
 
@@ -111,15 +182,14 @@ Use `git COMMAND --help` for showing the help!
 - `git show COMMIT`
 
 ## Changes
+- `git status`
 - `git diff`
 - `git diff --cached`
 
 ## Commit
-- `git add FILE`
 - `git add -p FILE`
-- `git reset FILE`
+- `git add FILE`
 - `git reset -p FILE`
+- `git reset FILE`
 - `git commit -m'COMMIT MSG'`
 - `git commit`
-
-[1]: https://chris.beams.io/posts/git-commit/