Explain text/eol/binary .gitattributes

[git-wiki.git] / pep-git.txt

diff --git a/pep-git.txt b/pep-git.txt
index b2e30384b9a98d101ab50d50f9942428e497603d..bb1d77b73f63e7e7e4036cdaf555afa96deaca6e 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -326,6 +326,11 @@ from it) you do that in two steps using two repositories: you push
 from the workstation to a bare repo on the remote host, ssh to the
 remote host and pull from the bare repo to a non-bare deployment repo.
 
+That changed in git 2.3, but see `the blog post
+<https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
+for caveats; in 2.4 the push-to-deploy feature was `further improved
+<https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
+
 Tags
 ''''
 
@@ -482,13 +487,39 @@ do something like::
 git revert: revert a commit
 ---------------------------
 
-How to undo a merge
-https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
+``git revert`` reverts a commit or commits, that is, it creates a new
+commit or commits that reverts the effects of the given commits. It's
+the only way to undo published commits (``git commit --amend``, ``git
+rebase`` and ``git reset`` change the branch in non-fast-forwardable
+ways so they should only be used for non-pushed commits.)
+
+There is a problem with reverting a merge commit. ``git revert`` can
+undo the code created by the merge commit but it cannot undo the fact
+of merge. See the discussion `How to revert a faulty merge
+<https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
 
 One thing that cannot be undone
 -------------------------------
 
-"Commit early, commit often".
+Whatever you undo, there is one thing that cannot be undone -
+overwritten uncommitted changes. Uncommitted changes don't belong to
+git so git cannot help preserving them.
+
+Most of the time git warns you when you're going to execute a command
+that overwrites uncommitted changes. Git warns you when you try to
+switch branches with ``git checkout``. It warns you when you're going
+to rebase with non-clean working tree. It refuses to pull new commits
+over non-committed files.
+
+But there are commands that do exactly that - overwrite files in the
+working tree. Commands like ``git checkout $PATHs`` or ``git reset
+--hard`` silently overwrite files including your uncommitted changes.
+
+With that in mind you can understand the stance "commit early, commit
+often". Commit as often as possible. Commit on every save in your
+editor or IDE. You can edit your commits before pushing - change,
+reorder, combine, remove. But save your changes in git database,
+either commit changes or at least stash them with ``git stash``.
 
 
 Merge or rebase?
@@ -559,10 +590,29 @@ Git has a builtin merge strategy for what Python core developers call
     $ git merge -s ours v1  # null-merge v1 into v2
 
 
-ReReRe
-======
+Advanced configuration
+======================
 
-https://git-scm.com/book/en/Git-Tools-Rerere
+Line endings
+------------
+
+Git has builtin mechanisms to handle line endings between platforms
+with different EOL styles. To allow git to do CRLF conversion assign
+``text`` attribute to files using `.gitattributes
+<https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
+For files that have to have specific line ending assign ``eol``
+attribute. For binary files the attribute is, naturally, ``binary``.
+
+For example::
+
+    $ cat .gitattributes
+    *.py text
+    *.txt text
+    *.png binary
+    /readme.txt eol=CRLF
+
+To check what attributes git uses for files use ``git check-attr``
+command.
 
 
 Advanced topics
@@ -579,15 +629,10 @@ Staging area aka index is a distinguishing feature of git. See
 Wiki.
 
 
-Advanced configuration
-======================
-
-Line endings
-------------
-
-Git has builtin mechanisms to handle line endings.
+ReReRe
+======
 
-TODO: describe crlf configuration and .gitattributes.
+https://git-scm.com/book/en/Git-Tools-Rerere
 
 
 Database maintenance