@matheusbsbs / matheus-bagliano / commits / f9666adfea
Fork 0

"assume unchanged" git: documentation.

This updates documentation to describe the "assume unchanged" behaviour. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Feb 12, 2006 at 01:48 UTC f9666adfead47d265a65c7ba6f90d0ebae3e6b21
2 files changed +84 -1
Documentation/git-ls-files.txt
+6 -1
@@ -8,7 +8,8 @@ git-ls-files - Information about files in the index/working directory
8
9 SYNOPSIS
10 --------
11 -'git-ls-files' [-z] [-t]
11 +[verse]
12 +'git-ls-files' [-z] [-t] [-v]
13 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
14 (-[c|d|o|i|s|u|k|m])\*
15 [-x <pattern>|--exclude=<pattern>]
@@ -82,6 +83,10 @@ OPTIONS
83 K:: to be killed
84 ? other
85
86 +-v::
87 + Similar to `-t`, but use lowercase letters for files
88 + that are marked as 'always matching index'.
89 +
90 --full-name::
91 When run from a subdirectory, the command usually
92 outputs paths relative to the current directory. This
Documentation/git-update-index.txt
+78
@@ -8,11 +8,14 @@ git-update-index - Modifies the index or directory cache
8
9 SYNOPSIS
10 --------
11 +[verse]
12 'git-update-index'
13 [--add] [--remove | --force-remove] [--replace]
14 [--refresh [-q] [--unmerged] [--ignore-missing]]
15 [--cacheinfo <mode> <object> <file>]\*
16 [--chmod=(+|-)x]
17 + [--assume-unchanged | --no-assume-unchanged]
18 + [--really-refresh]
19 [--info-only] [--index-info]
20 [-z] [--stdin]
21 [--verbose]
@@ -65,6 +68,18 @@ OPTIONS
68 --chmod=(+|-)x::
69 Set the execute permissions on the updated files.
70
71 +--assume-unchanged, --no-assume-unchanged::
72 + When these flags are specified, the object name recorded
73 + for the paths are not updated. Instead, these options
74 + sets and unsets the "assume unchanged" bit for the
75 + paths. When the "assume unchanged" bit is on, git stops
76 + checking the working tree files for possible
77 + modifications, so you need to manually unset the bit to
78 + tell git when you change the working tree file. This is
79 + sometimes helpful when working with a big project on a
80 + filesystem that has very slow lstat(2) system call
81 + (e.g. cifs).
82 +
83 --info-only::
84 Do not create objects in the object database for all
85 <file> arguments that follow this flag; just insert
@@ -193,6 +208,37 @@ $ git ls-files -s
208 ------------
209
210
211 +Using "assume unchanged" bit
212 +----------------------------
213 +
214 +Many operations in git depend on your filesystem to have an
215 +efficient `lstat(2)` implementation, so that `st_mtime`
216 +information for working tree files can be cheaply checked to see
217 +if the file contents have changed from the version recorded in
218 +the index file. Unfortunately, some filesystems have
219 +inefficient `lstat(2)`. If your filesystem is one of them, you
220 +can set "assume unchanged" bit to paths you have not changed to
221 +cause git not to do this check. Note that setting this bit on a
222 +path does not mean git will check the contents of the file to
223 +see if it has changed -- it makes git to omit any checking and
224 +assume it has *not* changed. When you make changes to working
225 +tree files, you have to explicitly tell git about it by dropping
226 +"assume unchanged" bit, either before or after you modify them.
227 +
228 +In order to set "assume unchanged" bit, use `--assume-unchanged`
229 +option. To unset, use `--no-assume-unchanged`.
230 +
231 +The command looks at `core.ignorestat` configuration variable. When
232 +this is true, paths updated with `git-update-index paths...` and
233 +paths updated with other git commands that update both index and
234 +working tree (e.g. `git-apply --index`, `git-checkout-index -u`,
235 +and `git-read-tree -u`) are automatically marked as "assume
236 +unchanged". Note that "assume unchanged" bit is *not* set if
237 +`git-update-index --refresh` finds the working tree file matches
238 +the index (use `git-update-index --really-refresh` if you want
239 +to mark them as "assume unchanged").
240 +
241 +
242 Examples
243 --------
244 To update and refresh only the files already checked out:
@@ -201,6 +247,35 @@ To update and refresh only the files already checked out:
247 $ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
248 ----------------
249
250 +On an inefficient filesystem with `core.ignorestat` set:
251 +
252 +------------
253 +$ git update-index --really-refresh <1>
254 +$ git update-index --no-assume-unchanged foo.c <2>
255 +$ git diff --name-only <3>
256 +$ edit foo.c
257 +$ git diff --name-only <4>
258 +M foo.c
259 +$ git update-index foo.c <5>
260 +$ git diff --name-only <6>
261 +$ edit foo.c
262 +$ git diff --name-only <7>
263 +$ git update-index --no-assume-unchanged foo.c <8>
264 +$ git diff --name-only <9>
265 +M foo.c
266 +
267 +<1> forces lstat(2) to set "assume unchanged" bits for paths
268 + that match index.
269 +<2> mark the path to be edited.
270 +<3> this does lstat(2) and finds index matches the path.
271 +<4> this does lstat(2) and finds index does not match the path.
272 +<5> registering the new version to index sets "assume unchanged" bit.
273 +<6> and it is assumed unchanged.
274 +<7> even after you edit it.
275 +<8> you can tell about the change after the fact.
276 +<9> now it checks with lstat(2) and finds it has been changed.
277 +------------
278 +
279
280 Configuration
281 -------------
@@ -213,6 +288,9 @@ in the index and the file mode on the filesystem if they differ only on
288 executable bit. On such an unfortunate filesystem, you may
289 need to use `git-update-index --chmod=`.
290
291 +The command looks at `core.ignorestat` configuration variable. See
292 +'Using "assume unchanged" bit' section above.
293 +
294
295 See Also
296 --------