Update documentation for stripspace
Tell the user what this command is intended for, and expand the description of what it does. Signed-off-by: Conrad Irwin <conrad.irwin@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Conrad Irwin committed
Dec 12, 2011 at 15:52 UTC
497215d8811ac7b8955693ceaad0899ecd894ed2
2 files changed
+64
-7
Documentation/git-stripspace.txt
+63
-6
@@ -3,26 +3,83 @@ git-stripspace(1)
3
4
NAME
5
----
6
-git-stripspace - Filter out empty lines
6
+git-stripspace - Remove unnecessary whitespace
7
8
9
SYNOPSIS
10
--------
11
[verse]
12
-'git stripspace' [-s | --strip-comments] < <stream>
12
+'git stripspace' [-s | --strip-comments] < input
13
14
DESCRIPTION
15
-----------
16
-Remove multiple empty lines, and empty lines at beginning and end.
16
+
17
+Clean the input in the manner used by 'git' for text such as commit
18
+messages, notes, tags and branch descriptions.
19
+
20
+With no arguments, this will:
21
+
22
+- remove trailing whitespace from all lines
23
+- collapse multiple consecutive empty lines into one empty line
24
+- remove empty lines from the beginning and end of the input
25
+- add a missing '\n' to the last line if necessary.
26
+
27
+In the case where the input consists entirely of whitespace characters, no
28
+output will be produced.
29
+
30
+*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix`
31
+mode of linkgit:git-apply[1] for correcting whitespace of patches or files in
32
+the repository.
33
34
OPTIONS
35
-------
36
-s::
37
--strip-comments::
22
- In addition to empty lines, also strip lines starting with '#'.
38
+ Skip and remove all lines starting with '#'.
39
+
40
+EXAMPLES
41
+--------
42
+
43
+Given the following noisy input with '$' indicating the end of a line:
44
24
-<stream>::
25
- Byte stream to act on.
45
+--------
46
+|A brief introduction $
47
+| $
48
+|$
49
+|A new paragraph$
50
+|# with a commented-out line $
51
+|explaining lots of stuff.$
52
+|$
53
+|# An old paragraph, also commented-out. $
54
+| $
55
+|The end.$
56
+| $
57
+---------
58
+
59
+Use 'git stripspace' with no arguments to obtain:
60
+
61
+--------
62
+|A brief introduction$
63
+|$
64
+|A new paragraph$
65
+|# with a commented-out line$
66
+|explaining lots of stuff.$
67
+|$
68
+|# An old paragraph, also commented-out.$
69
+|$
70
+|The end.$
71
+---------
72
+
73
+Use 'git stripspace --strip-comments' to obtain:
74
+
75
+--------
76
+|A brief introduction$
77
+|$
78
+|A new paragraph$
79
+|explaining lots of stuff.$
80
+|$
81
+|The end.$
82
+---------
83
84
GIT
85
---
builtin/stripspace.c
+1
-1
@@ -75,7 +75,7 @@ int cmd_stripspace(int argc, const char **argv, const char *prefix)
75
!strcmp(argv[1], "--strip-comments")))
76
strip_comments = 1;
77
else if (argc > 1)
78
- usage("git stripspace [-s | --strip-comments] < <stream>");
78
+ usage("git stripspace [-s | --strip-comments] < input");
79
80
if (strbuf_read(&buf, 0, 1024) < 0)
81
die_errno("could not read the input");