user-manual: create new "low-level git operations" chapter
The low-level index operations aren't as important to regular users as the rest of this "git concepts" chapter; so move it into a separate chapter, and do some minor cleanup. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
J. Bruce Fields committed
Sep 3, 2007 at 11:27 UTC
1c6045fffa55ee314717e26756182562e45976e6
1 file changed
+24
-9
Documentation/user-manual.txt
+24
-9
@@ -2963,29 +2963,41 @@ instantiated. So the index can be thought of as a write-back cache,
2963
which can contain dirty information that has not yet been written back
2964
to the backing store.
2965
2966
+[[low-level-operations]]
2967
+Low-level git operations
2968
+========================
2969
2970
+Many of the higher-level commands were originally implemented as shell
2971
+scripts using a smaller core of low-level git commands. These can still
2972
+be useful when doing unusual things with git, or just as a way to
2973
+understand its inner workings.
2974
2975
[[the-workflow]]
2976
The Workflow
2977
------------
2978
2979
+High-level operations such as gitlink:git-commit[1],
2980
+gitlink:git-checkout[1] and git-reset[1] work by moving data between the
2981
+working tree, the index, and the object database. Git provides
2982
+low-level operations which perform each of these steps individually.
2983
+
2984
Generally, all "git" operations work on the index file. Some operations
2985
work *purely* on the index file (showing the current state of the
2974
-index), but most operations move data to and from the index file. Either
2975
-from the database or from the working directory. Thus there are four
2976
-main combinations:
2986
+index), but most operations move data between the index file and either
2987
+the database or the working directory. Thus there are four main
2988
+combinations:
2989
2990
[[working-directory-to-index]]
2991
working directory -> index
2992
~~~~~~~~~~~~~~~~~~~~~~~~~~
2993
2982
-You update the index with information from the working directory with
2983
-the gitlink:git-update-index[1] command. You
2984
-generally update the index information by just specifying the filename
2985
-you want to update, like so:
2994
+The gitlink:git-update-index[1] command updates the index with
2995
+information from the working directory. You generally update the
2996
+index information by just specifying the filename you want to update,
2997
+like so:
2998
2999
-------------------------------------------------
2988
-$ git-update-index filename
3000
+$ git update-index filename
3001
-------------------------------------------------
3002
3003
but to avoid common mistakes with filename globbing etc, the command
@@ -3009,6 +3021,9 @@ stat information. It will 'not' update the object status itself, and
3021
it will only update the fields that are used to quickly test whether
3022
an object still matches its old backing store object.
3023
3024
+The previously introduced gitlink:git-add[1] is just a wrapper for
3025
+gitlink:git-update-index[1].
3026
+
3027
[[index-to-object-database]]
3028
index -> object database
3029
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3016,7 +3031,7 @@ index -> object database
3031
You write your current index file to a "tree" object with the program
3032
3033
-------------------------------------------------
3019
-$ git-write-tree
3034
+$ git write-tree
3035
-------------------------------------------------
3036
3037
that doesn't come with any options - it will just write out the