about summary refs log tree commit diff
path: root/third_party/git/Documentation/git-update-index.txt
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/git-update-index.txt')
-rw-r--r--third_party/git/Documentation/git-update-index.txt576
1 files changed, 0 insertions, 576 deletions
diff --git a/third_party/git/Documentation/git-update-index.txt b/third_party/git/Documentation/git-update-index.txt
deleted file mode 100644
index 1489cb09a099..000000000000
--- a/third_party/git/Documentation/git-update-index.txt
+++ /dev/null
@@ -1,576 +0,0 @@
-git-update-index(1)
-===================
-
-NAME
-----
-git-update-index - Register file contents in the working tree to the index
-
-
-SYNOPSIS
---------
-[verse]
-'git update-index'
-	     [--add] [--remove | --force-remove] [--replace]
-	     [--refresh] [-q] [--unmerged] [--ignore-missing]
-	     [(--cacheinfo <mode>,<object>,<file>)...]
-	     [--chmod=(+|-)x]
-	     [--[no-]assume-unchanged]
-	     [--[no-]skip-worktree]
-	     [--[no-]ignore-skip-worktree-entries]
-	     [--[no-]fsmonitor-valid]
-	     [--ignore-submodules]
-	     [--[no-]split-index]
-	     [--[no-|test-|force-]untracked-cache]
-	     [--[no-]fsmonitor]
-	     [--really-refresh] [--unresolve] [--again | -g]
-	     [--info-only] [--index-info]
-	     [-z] [--stdin] [--index-version <n>]
-	     [--verbose]
-	     [--] [<file>...]
-
-DESCRIPTION
------------
-Modifies the index or directory cache. Each file mentioned is updated
-into the index and any 'unmerged' or 'needs updating' state is
-cleared.
-
-See also linkgit:git-add[1] for a more user-friendly way to do some of
-the most common operations on the index.
-
-The way 'git update-index' handles files it is told about can be modified
-using the various options:
-
-OPTIONS
--------
---add::
-	If a specified file isn't in the index already then it's
-	added.
-	Default behaviour is to ignore new files.
-
---remove::
-	If a specified file is in the index but is missing then it's
-	removed.
-	Default behavior is to ignore removed file.
-
---refresh::
-	Looks at the current index and checks to see if merges or
-	updates are needed by checking stat() information.
-
--q::
-        Quiet.  If --refresh finds that the index needs an update, the
-        default behavior is to error out.  This option makes
-	'git update-index' continue anyway.
-
---ignore-submodules::
-	Do not try to update submodules.  This option is only respected
-	when passed before --refresh.
-
---unmerged::
-        If --refresh finds unmerged changes in the index, the default
-	behavior is to error out.  This option makes 'git update-index'
-        continue anyway.
-
---ignore-missing::
-	Ignores missing files during a --refresh
-
---cacheinfo <mode>,<object>,<path>::
---cacheinfo <mode> <object> <path>::
-	Directly insert the specified info into the index.  For
-	backward compatibility, you can also give these three
-	arguments as three separate parameters, but new users are
-	encouraged to use a single-parameter form.
-
---index-info::
-        Read index information from stdin.
-
---chmod=(+|-)x::
-        Set the execute permissions on the updated files.
-
---[no-]assume-unchanged::
-	When this flag is specified, the object names recorded
-	for the paths are not updated.  Instead, this option
-	sets/unsets the "assume unchanged" bit for the
-	paths.  When the "assume unchanged" bit is on, the user
-	promises not to change the file and allows Git to assume
-	that the working tree file matches what is recorded in
-	the index.  If you want to change the working tree file,
-	you need to unset the bit to tell Git.  This is
-	sometimes helpful when working with a big project on a
-	filesystem that has very slow lstat(2) system call
-	(e.g. cifs).
-+
-Git will fail (gracefully) in case it needs to modify this file
-in the index e.g. when merging in a commit;
-thus, in case the assumed-untracked file is changed upstream,
-you will need to handle the situation manually.
-
---really-refresh::
-	Like `--refresh`, but checks stat information unconditionally,
-	without regard to the "assume unchanged" setting.
-
---[no-]skip-worktree::
-	When one of these flags is specified, the object name recorded
-	for the paths are not updated. Instead, these options
-	set and unset the "skip-worktree" bit for the paths. See
-	section "Skip-worktree bit" below for more information.
-
-
---[no-]ignore-skip-worktree-entries::
-	Do not remove skip-worktree (AKA "index-only") entries even when
-	the `--remove` option was specified.
-
---[no-]fsmonitor-valid::
-	When one of these flags is specified, the object name recorded
-	for the paths are not updated. Instead, these options
-	set and unset the "fsmonitor valid" bit for the paths. See
-	section "File System Monitor" below for more information.
-
--g::
---again::
-	Runs 'git update-index' itself on the paths whose index
-	entries are different from those from the `HEAD` commit.
-
---unresolve::
-	Restores the 'unmerged' or 'needs updating' state of a
-	file during a merge if it was cleared by accident.
-
---info-only::
-	Do not create objects in the object database for all
-	<file> arguments that follow this flag; just insert
-	their object IDs into the index.
-
---force-remove::
-	Remove the file from the index even when the working directory
-	still has such a file. (Implies --remove.)
-
---replace::
-	By default, when a file `path` exists in the index,
-	'git update-index' refuses an attempt to add `path/file`.
-	Similarly if a file `path/file` exists, a file `path`
-	cannot be added.  With --replace flag, existing entries
-	that conflict with the entry being added are
-	automatically removed with warning messages.
-
---stdin::
-	Instead of taking list of paths from the command line,
-	read list of paths from the standard input.  Paths are
-	separated by LF (i.e. one path per line) by default.
-
---verbose::
-        Report what is being added and removed from index.
-
---index-version <n>::
-	Write the resulting index out in the named on-disk format version.
-	Supported versions are 2, 3 and 4. The current default version is 2
-	or 3, depending on whether extra features are used, such as
-	`git add -N`.
-+
-Version 4 performs a simple pathname compression that reduces index
-size by 30%-50% on large repositories, which results in faster load
-time. Version 4 is relatively young (first released in 1.8.0 in
-October 2012). Other Git implementations such as JGit and libgit2
-may not support it yet.
-
--z::
-	Only meaningful with `--stdin` or `--index-info`; paths are
-	separated with NUL character instead of LF.
-
---split-index::
---no-split-index::
-	Enable or disable split index mode. If split-index mode is
-	already enabled and `--split-index` is given again, all
-	changes in $GIT_DIR/index are pushed back to the shared index
-	file.
-+
-These options take effect whatever the value of the `core.splitIndex`
-configuration variable (see linkgit:git-config[1]). But a warning is
-emitted when the change goes against the configured value, as the
-configured value will take effect next time the index is read and this
-will remove the intended effect of the option.
-
---untracked-cache::
---no-untracked-cache::
-	Enable or disable untracked cache feature. Please use
-	`--test-untracked-cache` before enabling it.
-+
-These options take effect whatever the value of the `core.untrackedCache`
-configuration variable (see linkgit:git-config[1]). But a warning is
-emitted when the change goes against the configured value, as the
-configured value will take effect next time the index is read and this
-will remove the intended effect of the option.
-
---test-untracked-cache::
-	Only perform tests on the working directory to make sure
-	untracked cache can be used. You have to manually enable
-	untracked cache using `--untracked-cache` or
-	`--force-untracked-cache` or the `core.untrackedCache`
-	configuration variable afterwards if you really want to use
-	it. If a test fails the exit code is 1 and a message
-	explains what is not working as needed, otherwise the exit
-	code is 0 and OK is printed.
-
---force-untracked-cache::
-	Same as `--untracked-cache`. Provided for backwards
-	compatibility with older versions of Git where
-	`--untracked-cache` used to imply `--test-untracked-cache` but
-	this option would enable the extension unconditionally.
-
---fsmonitor::
---no-fsmonitor::
-	Enable or disable files system monitor feature. These options
-	take effect whatever the value of the `core.fsmonitor`
-	configuration variable (see linkgit:git-config[1]). But a warning
-	is emitted when the change goes against the configured value, as
-	the configured value will take effect next time the index is
-	read and this will remove the intended effect of the option.
-
-\--::
-	Do not interpret any more arguments as options.
-
-<file>::
-	Files to act on.
-	Note that files beginning with '.' are discarded. This includes
-	`./file` and `dir/./file`. If you don't want this, then use
-	cleaner names.
-	The same applies to directories ending '/' and paths with '//'
-
-USING --REFRESH
----------------
-`--refresh` does not calculate a new sha1 file or bring the index
-up to date for mode/content changes. But what it *does* do is to
-"re-match" the stat information of a file with the index, so that you
-can refresh the index for a file that hasn't been changed but where
-the stat entry is out of date.
-
-For example, you'd want to do this after doing a 'git read-tree', to link
-up the stat index details with the proper files.
-
-USING --CACHEINFO OR --INFO-ONLY
---------------------------------
-`--cacheinfo` is used to register a file that is not in the
-current working directory.  This is useful for minimum-checkout
-merging.
-
-To pretend you have a file at path with mode and sha1, say:
-
-----------------
-$ git update-index --add --cacheinfo <mode>,<sha1>,<path>
-----------------
-
-`--info-only` is used to register files without placing them in the object
-database.  This is useful for status-only repositories.
-
-Both `--cacheinfo` and `--info-only` behave similarly: the index is updated
-but the object database isn't.  `--cacheinfo` is useful when the object is
-in the database but the file isn't available locally.  `--info-only` is
-useful when the file is available, but you do not wish to update the
-object database.
-
-
-USING --INDEX-INFO
-------------------
-
-`--index-info` is a more powerful mechanism that lets you feed
-multiple entry definitions from the standard input, and designed
-specifically for scripts.  It can take inputs of three formats:
-
-    . mode SP type SP sha1          TAB path
-+
-This format is to stuff `git ls-tree` output into the index.
-
-    . mode         SP sha1 SP stage TAB path
-+
-This format is to put higher order stages into the
-index file and matches 'git ls-files --stage' output.
-
-    . mode         SP sha1          TAB path
-+
-This format is no longer produced by any Git command, but is
-and will continue to be supported by `update-index --index-info`.
-
-To place a higher stage entry to the index, the path should
-first be removed by feeding a mode=0 entry for the path, and
-then feeding necessary input lines in the third format.
-
-For example, starting with this index:
-
-------------
-$ git ls-files -s
-100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0       frotz
-------------
-
-you can feed the following input to `--index-info`:
-
-------------
-$ git update-index --index-info
-0 0000000000000000000000000000000000000000	frotz
-100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
-100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz
-------------
-
-The first line of the input feeds 0 as the mode to remove the
-path; the SHA-1 does not matter as long as it is well formatted.
-Then the second and third line feeds stage 1 and stage 2 entries
-for that path.  After the above, we would end up with this:
-
-------------
-$ git ls-files -s
-100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
-100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz
-------------
-
-
-USING ``ASSUME UNCHANGED'' BIT
-------------------------------
-
-Many operations in Git depend on your filesystem to have an
-efficient `lstat(2)` implementation, so that `st_mtime`
-information for working tree files can be cheaply checked to see
-if the file contents have changed from the version recorded in
-the index file.  Unfortunately, some filesystems have
-inefficient `lstat(2)`.  If your filesystem is one of them, you
-can set "assume unchanged" bit to paths you have not changed to
-cause Git not to do this check.  Note that setting this bit on a
-path does not mean Git will check the contents of the file to
-see if it has changed -- it makes Git to omit any checking and
-assume it has *not* changed.  When you make changes to working
-tree files, you have to explicitly tell Git about it by dropping
-"assume unchanged" bit, either before or after you modify them.
-
-In order to set "assume unchanged" bit, use `--assume-unchanged`
-option.  To unset, use `--no-assume-unchanged`. To see which files
-have the "assume unchanged" bit set, use `git ls-files -v`
-(see linkgit:git-ls-files[1]).
-
-The command looks at `core.ignorestat` configuration variable.  When
-this is true, paths updated with `git update-index paths...` and
-paths updated with other Git commands that update both index and
-working tree (e.g. 'git apply --index', 'git checkout-index -u',
-and 'git read-tree -u') are automatically marked as "assume
-unchanged".  Note that "assume unchanged" bit is *not* set if
-`git update-index --refresh` finds the working tree file matches
-the index (use `git update-index --really-refresh` if you want
-to mark them as "assume unchanged").
-
-
-EXAMPLES
---------
-To update and refresh only the files already checked out:
-
-----------------
-$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
-----------------
-
-On an inefficient filesystem with `core.ignorestat` set::
-+
-------------
-$ git update-index --really-refresh              <1>
-$ git update-index --no-assume-unchanged foo.c   <2>
-$ git diff --name-only                           <3>
-$ edit foo.c
-$ git diff --name-only                           <4>
-M foo.c
-$ git update-index foo.c                         <5>
-$ git diff --name-only                           <6>
-$ edit foo.c
-$ git diff --name-only                           <7>
-$ git update-index --no-assume-unchanged foo.c   <8>
-$ git diff --name-only                           <9>
-M foo.c
-------------
-+
-<1> forces lstat(2) to set "assume unchanged" bits for paths that match index.
-<2> mark the path to be edited.
-<3> this does lstat(2) and finds index matches the path.
-<4> this does lstat(2) and finds index does *not* match the path.
-<5> registering the new version to index sets "assume unchanged" bit.
-<6> and it is assumed unchanged.
-<7> even after you edit it.
-<8> you can tell about the change after the fact.
-<9> now it checks with lstat(2) and finds it has been changed.
-
-
-SKIP-WORKTREE BIT
------------------
-
-Skip-worktree bit can be defined in one (long) sentence: When reading
-an entry, if it is marked as skip-worktree, then Git pretends its
-working directory version is up to date and read the index version
-instead.
-
-To elaborate, "reading" means checking for file existence, reading
-file attributes or file content. The working directory version may be
-present or absent. If present, its content may match against the index
-version or not. Writing is not affected by this bit, content safety
-is still first priority. Note that Git _can_ update working directory
-file, that is marked skip-worktree, if it is safe to do so (i.e.
-working directory version matches index version)
-
-Although this bit looks similar to assume-unchanged bit, its goal is
-different from assume-unchanged bit's. Skip-worktree also takes
-precedence over assume-unchanged bit when both are set.
-
-SPLIT INDEX
------------
-
-This mode is designed for repositories with very large indexes, and
-aims at reducing the time it takes to repeatedly write these indexes.
-
-In this mode, the index is split into two files, $GIT_DIR/index and
-$GIT_DIR/sharedindex.<SHA-1>. Changes are accumulated in
-$GIT_DIR/index, the split index, while the shared index file contains
-all index entries and stays unchanged.
-
-All changes in the split index are pushed back to the shared index
-file when the number of entries in the split index reaches a level
-specified by the splitIndex.maxPercentChange config variable (see
-linkgit:git-config[1]).
-
-Each time a new shared index file is created, the old shared index
-files are deleted if their modification time is older than what is
-specified by the splitIndex.sharedIndexExpire config variable (see
-linkgit:git-config[1]).
-
-To avoid deleting a shared index file that is still used, its
-modification time is updated to the current time every time a new split
-index based on the shared index file is either created or read from.
-
-UNTRACKED CACHE
----------------
-
-This cache is meant to speed up commands that involve determining
-untracked files such as `git status`.
-
-This feature works by recording the mtime of the working tree
-directories and then omitting reading directories and stat calls
-against files in those directories whose mtime hasn't changed. For
-this to work the underlying operating system and file system must
-change the `st_mtime` field of directories if files in the directory
-are added, modified or deleted.
-
-You can test whether the filesystem supports that with the
-`--test-untracked-cache` option. The `--untracked-cache` option used
-to implicitly perform that test in older versions of Git, but that's
-no longer the case.
-
-If you want to enable (or disable) this feature, it is easier to use
-the `core.untrackedCache` configuration variable (see
-linkgit:git-config[1]) than using the `--untracked-cache` option to
-`git update-index` in each repository, especially if you want to do so
-across all repositories you use, because you can set the configuration
-variable to `true` (or `false`) in your `$HOME/.gitconfig` just once
-and have it affect all repositories you touch.
-
-When the `core.untrackedCache` configuration variable is changed, the
-untracked cache is added to or removed from the index the next time a
-command reads the index; while when `--[no-|force-]untracked-cache`
-are used, the untracked cache is immediately added to or removed from
-the index.
-
-Before 2.17, the untracked cache had a bug where replacing a directory
-with a symlink to another directory could cause it to incorrectly show
-files tracked by git as untracked. See the "status: add a failing test
-showing a core.untrackedCache bug" commit to git.git. A workaround for
-that is (and this might work for other undiscovered bugs in the
-future):
-
-----------------
-$ git -c core.untrackedCache=false status
-----------------
-
-This bug has also been shown to affect non-symlink cases of replacing
-a directory with a file when it comes to the internal structures of
-the untracked cache, but no case has been reported where this resulted in
-wrong "git status" output.
-
-There are also cases where existing indexes written by git versions
-before 2.17 will reference directories that don't exist anymore,
-potentially causing many "could not open directory" warnings to be
-printed on "git status". These are new warnings for existing issues
-that were previously silently discarded.
-
-As with the bug described above the solution is to one-off do a "git
-status" run with `core.untrackedCache=false` to flush out the leftover
-bad data.
-
-FILE SYSTEM MONITOR
--------------------
-
-This feature is intended to speed up git operations for repos that have
-large working directories.
-
-It enables git to work together with a file system monitor (see the
-"fsmonitor-watchman" section of linkgit:githooks[5]) that can
-inform it as to what files have been modified. This enables git to avoid
-having to lstat() every file to find modified files.
-
-When used in conjunction with the untracked cache, it can further improve
-performance by avoiding the cost of scanning the entire working directory
-looking for new files.
-
-If you want to enable (or disable) this feature, it is easier to use
-the `core.fsmonitor` configuration variable (see
-linkgit:git-config[1]) than using the `--fsmonitor` option to
-`git update-index` in each repository, especially if you want to do so
-across all repositories you use, because you can set the configuration
-variable in your `$HOME/.gitconfig` just once and have it affect all
-repositories you touch.
-
-When the `core.fsmonitor` configuration variable is changed, the
-file system monitor is added to or removed from the index the next time
-a command reads the index. When `--[no-]fsmonitor` are used, the file
-system monitor is immediately added to or removed from the index.
-
-CONFIGURATION
--------------
-
-The command honors `core.filemode` configuration variable.  If
-your repository is on a filesystem whose executable bits are
-unreliable, this should be set to 'false' (see linkgit:git-config[1]).
-This causes the command to ignore differences in file modes recorded
-in the index and the file mode on the filesystem if they differ only on
-executable bit.   On such an unfortunate filesystem, you may
-need to use 'git update-index --chmod='.
-
-Quite similarly, if `core.symlinks` configuration variable is set
-to 'false' (see linkgit:git-config[1]), symbolic links are checked out
-as plain files, and this command does not modify a recorded file mode
-from symbolic link to regular file.
-
-The command looks at `core.ignorestat` configuration variable.  See
-'Using "assume unchanged" bit' section above.
-
-The command also looks at `core.trustctime` configuration variable.
-It can be useful when the inode change time is regularly modified by
-something outside Git (file system crawlers and backup systems use
-ctime for marking files processed) (see linkgit:git-config[1]).
-
-The untracked cache extension can be enabled by the
-`core.untrackedCache` configuration variable (see
-linkgit:git-config[1]).
-
-NOTES
------
-
-Users often try to use the assume-unchanged and skip-worktree bits
-to tell Git to ignore changes to files that are tracked.  This does not
-work as expected, since Git may still check working tree files against
-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.
-
-For example, if the file you want to change is some sort of config file,
-the repository can include a sample config file that can then be copied
-into the ignored name and modified.  The repository can even include a
-script to treat the sample file as a template, modifying and copying it
-automatically.
-
-SEE ALSO
---------
-linkgit:git-config[1],
-linkgit:git-add[1],
-linkgit:git-ls-files[1]
-
-GIT
----
-Part of the linkgit:git[1] suite