This series includes four patches that update the documentation to
address common user misconceptions.
Changes from v2:
* Move author and committer information to git-commit(1) where people
will look for it.
* Move guidance on user.name format to git-commit(1) as well and mention
a shortened form of the advice in the `user.name` description.
* Use a parenthetical to describe a "personal name" without contrasting
it with a username.
* Offer a potential solution for people who want to ignore tracked
files by recommending a templating mechanism.
* Be slightly more verbose about why memory is wasted with
http.postBuffer.
Changes from v1:
* Remove parenthetical which was confusing.
* Add two more patches.
brian m. carlson (4):
doc: move author and committer information to git-commit(1)
doc: provide guidance on user.name format
doc: dissuade users from trying to ignore tracked files
docs: mention when increasing http.postBuffer is valuable
Documentation/config/http.txt | 8 ++++++
Documentation/config/user.txt | 7 +++++-
Documentation/git-commit-tree.txt | 39 ++++-------------------------
Documentation/git-commit.txt | 40 +++++++++++++++++++++++++++---
Documentation/git-update-index.txt | 16 ++++++++++++
5 files changed, 72 insertions(+), 38 deletions(-)
Range-diff against v2:
1: 603a9f8f9a < -: ---------- doc: provide guidance on user.name format
-: ---------- > 1: b39b365f54 doc: move author and committer information to git-commit(1)
-: ---------- > 2: b7d805427c doc: provide guidance on user.name format
2: 0da41623a5 ! 3: 7644af0b07 doc: dissuade users from trying to ignore tracked files
@@ Commit message
pitfalls in the documentation for git update-index so that users know
they should explore alternate solutions.
+ In additon, let's provide a recommended solution to dealing with the
+ common case of configuration files, since there are well-known
+ approaches used successfully in many environments.
+
Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx>
## Documentation/git-update-index.txt ##
@@ Documentation/git-update-index.txt: The untracked cache extension can be enabled
+the index when performing certain operations. In general, Git does not
+provide a way to ignore changes to tracked files, so alternate solutions
+are recommended.
++
++If the file you want to change is some sort of configuration file (say,
++for a build tool, IDE, or editor), a common solution is to use a
++templating mechanism, such as Ruby's ERB, to generate the ignored
++configuration file from a template stored in the repository and a source
++of data using a script or build step.
+
SEE ALSO
--------
3: 89fe11b951 ! 4: d096763e7a docs: mention when increasing http.postBuffer is valuable
@@ Documentation/config/http.txt: http.postBuffer::
+server or a proxy only supports HTTP/1.0 or is noncompliant with the
+HTTP standard. Raising this is not, in general, an effective solution
+for most push problems, but can increase memory consumption
-+significantly.
++significantly since the entire buffer is allocated for even small
++pushes.
http.lowSpeedLimit, http.lowSpeedTime::
If the HTTP transfer speed is less than 'http.lowSpeedLimit'
