From 915cd9bb00e770c8b6862d4d79a192d45605e1ca Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 20 Jul 2008 01:24:17 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.6.4-433-g09651 --- RelNotes-1.5.6.4.txt | 16 ++-- RelNotes-1.6.0.txt | 13 ++- git-fast-import.html | 9 +- git-fast-import.txt | 3 + git-merge.html | 90 +++++++++---------- git-merge.txt | 76 +++++++--------- git-submodule.html | 66 +++++++++----- git-submodule.txt | 69 ++++++++++----- git-update-index.html | 11 ++- git-update-index.txt | 10 +++ git.html | 2 +- git.txt | 9 +- gitignore.html | 13 ++- gitignore.txt | 11 ++- technical/api-run-command.html | 154 +++++++++++++++++++++------------ technical/api-run-command.txt | 2 +- 16 files changed, 338 insertions(+), 216 deletions(-) diff --git a/RelNotes-1.5.6.4.txt b/RelNotes-1.5.6.4.txt index 130418864..d8968f1ec 100644 --- a/RelNotes-1.5.6.4.txt +++ b/RelNotes-1.5.6.4.txt @@ -28,16 +28,20 @@ Fixes since v1.5.6.3 be huge by saying "no common commits", but this was an unnecessary noise; it is already known by the user anyway. +* "git-http-fetch" would have segfaulted when pack idx file retrieved + from the other side was corrupt. + +* "git-index-pack" used too much memory when dealing with a deep delta chain. + * "git-mailinfo" (hence "git-am") did not correctly handle in-body [PATCH] line to override the commit title taken from the mail Subject header. * "git-rebase -i -p" lost parents that are not involved in the history being rewritten. -Contains other various documentation fixes. +* "git-rm" lost track of where the index file was when GIT_DIR was + specified as a relative path. --- -exec >/var/tmp/1 -echo O=$(git describe maint) -O=v1.5.6.3-21-gebcce31 -git shortlog --no-merges $O..maint +* "git-rev-list --quiet" was not quiet as advertised. + +Contains other various documentation fixes. diff --git a/RelNotes-1.6.0.txt b/RelNotes-1.6.0.txt index b29ba2522..7da62d08d 100644 --- a/RelNotes-1.6.0.txt +++ b/RelNotes-1.6.0.txt @@ -21,7 +21,9 @@ main git.git codebase. By default, packfiles created with this version uses delta-base-offset encoding introduced in v1.4.4. Pack idx files are using version 2 that allows larger packs and added robustness thanks to its CRC checking, -introduced in v1.5.2. +introduced in v1.5.2 and v1.4.4.5. If you want to keep your repositories +backwards compatible past these versions, set repack.useDeltaBaseOffset +to false or pack.indexVersion to 1, respectively. GIT_CONFIG, which was only documented as affecting "git config", but actually affected all git commands, now only affects "git config". @@ -134,6 +136,9 @@ Updates since v1.5.6 * git-archive can be told to omit certain paths from its output using export-ignore attributes. +* git-archive uses the zlib default compression level when creating + zip archive. + * With -v option, git-branch describes the remote tracking statistics similar to the way git-checkout reports by how many commits your branch is ahead/behind. @@ -153,6 +158,8 @@ Updates since v1.5.6 * git-clone can clone from a remote whose URL would be rewritten by configuration stored in $HOME/.gitconfig now. +* git-cvsserver learned to respond to "cvs co -c". + * git-diff --check now checks leftover merge conflict markers. * When remote side used to have branch 'foo' and git-fetch finds that now @@ -164,6 +171,8 @@ Updates since v1.5.6 * fast-export learned to export and import marks file; this can be used to interface with fast-import incrementally. +* fast-import and fast-export learned to export and import gitlinks. + * git-rebase records the original tip of branch in ORIG_HEAD before it is rewound. @@ -208,6 +217,6 @@ this release, unless otherwise noted. --- exec >/var/tmp/1 -O=v1.5.6.3-436-g1f8dc67 +O=v1.5.6.4-432-g6796399 echo O=$(git describe refs/heads/master) git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/git-fast-import.html b/git-fast-import.html index 5b0932dbf..e9066a5e1 100644 --- a/git-fast-import.html +++ b/git-fast-import.html @@ -875,6 +875,13 @@ in octal. Git only supports the following modes:

120000: A symlink, the content of the file will be the link target.

+
  • +

    +160000: A gitlink, SHA-1 of the object refers to a commit in + another repository. Git links can only be specified by SHA or through + a commit mark. They are used to implement submodules. +

    +

    • In both formats <path> is the complete path of the file to be added (if not already existing) or modified (if already existing).

    @@ -1464,7 +1471,7 @@ memory footprint (less than 2.7 MiB per active branch).

    diff --git a/git-fast-import.txt b/git-fast-import.txt index 2d01d0d10..c2f483a8d 100644 --- a/git-fast-import.txt +++ b/git-fast-import.txt @@ -481,6 +481,9 @@ in octal. Git only supports the following modes: what you want. * `100755` or `755`: A normal, but executable, file. * `120000`: A symlink, the content of the file will be the link target. +* `160000`: A gitlink, SHA-1 of the object refers to a commit in + another repository. Git links can only be specified by SHA or through + a commit mark. They are used to implement submodules. In both formats `` is the complete path of the file to be added (if not already existing) or modified (if already existing). diff --git a/git-merge.html b/git-merge.html index 46166165c..1e0bf58a0 100644 --- a/git-merge.html +++ b/git-merge.html @@ -657,52 +657,41 @@ branch.<name>.mergeoptions

    A merge is always between the current HEAD and one or more commits (usually, branch head or tag), and the index file must -exactly match the -tree of HEAD commit (i.e. the contents of the last commit) when -it happens. In other words, git diff --cached HEAD must -report no changes.

    -
    - - - -
    -
    Note
    -    		This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the HEAD commit. The most -notable case is when your HEAD commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your HEAD commit. Also, your index entries -may have differences from your HEAD commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail.
    -
    -

    Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with git pull remote rbranch:lbranch, but your working tree, -.git/HEAD pointer and index file are left intact). In addition, -merge always sets .git/ORIG_HEAD to the original state of HEAD so -a problematic merge can be removed by using git reset ORIG_HEAD.

    -

    You may have local modifications in the working tree files. In -other words, git-diff is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything.

    -

    So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready.

    -

    When things cleanly merge, these things happen:

    +match the tree of HEAD commit (i.e. the contents of the last commit) +when it starts out. In other words, git diff --cached HEAD must +report no changes. (One exception is when the changed index +entries are already in the same state that would result from +the merge anyway.)

    +

    Three kinds of merge can happen:

    +
      +
    • +

      +The merged commit is already contained in HEAD. This is the + simplest case, called "Already up-to-date." +

      +
      • +
    • +

      +HEAD is already contained in the merged commit. This is the + most common case especially when involved through git pull: + you are tracking an upstream repository, committed no local + changes and now you want to update to a newer upstream revision. + Your HEAD (and the index) is updated to at point the merged + commit, without creating an extra merge commit. This is + called "Fast-forward". +

      +
      • +
    • +

      +Both the merged commit and HEAD are independent and must be + tied together by a merge commit that has them both as its parents. + The rest of this section describes this "True merge" case. +

      +
      • +
    +

    The chosen merge strategy merges the two commits into a single +new source tree. +When things cleanly merge, these things happen:

    1. @@ -773,15 +762,16 @@ No other changes are done. In particular, the local

      Decide not to merge. The only clean-up you need are to reset the index file to the HEAD commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; git-reset can + up working tree changes made by 2. and 3.; git-reset --hard can be used for this.

    2. Resolve the conflicts. git diff would report only the - conflicting paths because of the above 2. and 3. Edit the - working tree files into a desirable shape, git-add or git-rm + conflicting paths because of the above 2. and 3. + Edit the working tree files into a desirable shape + (git mergetool can ease this task), git-add or git-rm them, to make the index file contain what the merge result should be, and run git-commit to commit the result.

      @@ -811,7 +801,7 @@ Resolve the conflicts. git diff would report only the
    diff --git a/git-merge.txt b/git-merge.txt index 019e4ca8f..a7487d3df 100644 --- a/git-merge.txt +++ b/git-merge.txt @@ -57,50 +57,31 @@ HOW MERGE WORKS A merge is always between the current `HEAD` and one or more commits (usually, branch head or tag), and the index file must -exactly match the -tree of `HEAD` commit (i.e. the contents of the last commit) when -it happens. In other words, `git diff --cached HEAD` must -report no changes. - -[NOTE] -This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the `HEAD` commit. The most -notable case is when your `HEAD` commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your `HEAD` commit. Also, your index entries -may have differences from your `HEAD` commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail. - -Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with `git pull remote rbranch:lbranch`, but your working tree, -`.git/HEAD` pointer and index file are left intact). In addition, -merge always sets `.git/ORIG_HEAD` to the original state of HEAD so -a problematic merge can be removed by using `git reset ORIG_HEAD`. - -You may have local modifications in the working tree files. In -other words, 'git-diff' is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything. - -So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready. - +match the tree of `HEAD` commit (i.e. the contents of the last commit) +when it starts out. In other words, `git diff --cached HEAD` must +report no changes. (One exception is when the changed index +entries are already in the same state that would result from +the merge anyway.) + +Three kinds of merge can happen: + +* The merged commit is already contained in `HEAD`. This is the + simplest case, called "Already up-to-date." + +* `HEAD` is already contained in the merged commit. This is the + most common case especially when involved through 'git pull': + you are tracking an upstream repository, committed no local + changes and now you want to update to a newer upstream revision. + Your `HEAD` (and the index) is updated to at point the merged + commit, without creating an extra merge commit. This is + called "Fast-forward". + +* Both the merged commit and `HEAD` are independent and must be + tied together by a merge commit that has them both as its parents. + The rest of this section describes this "True merge" case. + +The chosen merge strategy merges the two commits into a single +new source tree. When things cleanly merge, these things happen: 1. The results are updated both in the index file and in your @@ -142,12 +123,13 @@ After seeing a conflict, you can do two things: * Decide not to merge. The only clean-up you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; 'git-reset' can + up working tree changes made by 2. and 3.; 'git-reset --hard' can be used for this. * Resolve the conflicts. `git diff` would report only the - conflicting paths because of the above 2. and 3. Edit the - working tree files into a desirable shape, 'git-add' or 'git-rm' + conflicting paths because of the above 2. and 3. + Edit the working tree files into a desirable shape + ('git mergetool' can ease this task), 'git-add' or 'git-rm' them, to make the index file contain what the merge result should be, and run 'git-commit' to commit the result. diff --git a/git-submodule.html b/git-submodule.html index 1ecc633ff..0c1b2a5a7 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -329,22 +329,41 @@ git-submodule(1) Manual Page

    DESCRIPTION

    -

    Submodules are a special kind of tree entries which refer to a particular tree -state in another repository. The tree entry describes -the existence of a submodule with the given name and the exact revision that -should be used, while an entry in .gitmodules file gives the location of -the repository.

    -

    When checked out, submodules will maintain their own independent repositories -within their directories; the only link between the submodule and the "parent -project" is the tree entry within the parent project mentioned above.

    -

    This command will manage the tree entries and contents of the gitmodules file -for you, as well as inspecting the status of your submodules and updating them. -When adding a new submodule to the tree, the add subcommand is to be used. -However, when pulling a tree containing submodules, these will not be checked -out by default; the init and update subcommands will maintain submodules -checked out and at appropriate revision in your working tree. You can inspect -the current status of your submodules using the submodule subcommand and get -an overview of changes update would perform using the summary subcommand.

    +

    Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit.

    +

    They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the subtree merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route.

    +

    Submodules are composed from a so-called gitlink tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the .gitmodules file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see submodule init).

    +

    This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the add subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the init and update subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the status subcommand and get a detailed overview of the +difference between the index and checkouts using the summary +subcommand.

    COMMANDS

    @@ -397,10 +416,15 @@ init

    - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - submodule.$name.url. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is submodule.$name.url. + This command does not alter existing information in .git/config. + You can then customize the submodule clone URLs in .git/config + for your local setup and proceed to git submodule update; + you can also just use git submodule update --init without + the explicit init step if you do not intend to customize + any submodule locations.

    @@ -509,7 +533,7 @@ for details.

    diff --git a/git-submodule.txt b/git-submodule.txt index bb4e6fbf5..829b03201 100644 --- a/git-submodule.txt +++ b/git-submodule.txt @@ -18,24 +18,44 @@ SYNOPSIS DESCRIPTION ----------- -Submodules are a special kind of tree entries which refer to a particular tree -state in another repository. The tree entry describes -the existence of a submodule with the given name and the exact revision that -should be used, while an entry in `.gitmodules` file gives the location of -the repository. - -When checked out, submodules will maintain their own independent repositories -within their directories; the only link between the submodule and the "parent -project" is the tree entry within the parent project mentioned above. - -This command will manage the tree entries and contents of the gitmodules file -for you, as well as inspecting the status of your submodules and updating them. -When adding a new submodule to the tree, the 'add' subcommand is to be used. -However, when pulling a tree containing submodules, these will not be checked -out by default; the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. You can inspect -the current status of your submodules using the 'submodule' subcommand and get -an overview of changes 'update' would perform using the 'summary' subcommand. +Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit. + +They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. + +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the 'add' subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the 'status' subcommand and get a detailed overview of the +difference between the index and checkouts using the 'summary' +subcommand. COMMANDS @@ -78,10 +98,15 @@ status:: repository. This command is the default command for 'git-submodule'. init:: - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - `submodule.$name.url`. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is `submodule.$name.url`. + This command does not alter existing information in .git/config. + You can then customize the submodule clone URLs in .git/config + for your local setup and proceed to 'git submodule update'; + you can also just use 'git submodule update --init' without + the explicit 'init' step if you do not intend to customize + any submodule locations. update:: Update the registered submodules, i.e. clone missing submodules and diff --git a/git-update-index.html b/git-update-index.html index be8215530..90099e2cd 100644 --- a/git-update-index.html +++ b/git-update-index.html @@ -452,6 +452,15 @@ using the various options:

    filesystem that has very slow lstat(2) system call (e.g. cifs).

    +

    This option can be also used as a coarse file-level mechanism +to ignore uncommitted changes in tracked files (akin to what +.gitignore does for untracked files). +You should remember that an explicit git add operation will +still cause the file to be refreshed from the working tree. +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.

    -g @@ -781,7 +790,7 @@ from symbolic link to regular file.

    diff --git a/git-update-index.txt b/git-update-index.txt index a91fd214d..6b930bc16 100644 --- a/git-update-index.txt +++ b/git-update-index.txt @@ -88,6 +88,16 @@ OPTIONS sometimes helpful when working with a big project on a filesystem that has very slow lstat(2) system call (e.g. cifs). ++ +This option can be also used as a coarse file-level mechanism +to ignore uncommitted changes in tracked files (akin to what +`.gitignore` does for untracked files). +You should remember that an explicit 'git add' operation will +still cause the file to be refreshed from the working tree. +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. -g:: --again:: diff --git a/git.html b/git.html index 53a20c73b..ad11a4eb3 100644 --- a/git.html +++ b/git.html @@ -2024,7 +2024,7 @@ contributors on the git-list <git@vger.kernel.org>.

    diff --git a/git.txt b/git.txt index 27b9d31f7..44ea35e94 100644 --- a/git.txt +++ b/git.txt @@ -43,12 +43,13 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.6.3/git.html[documentation for release 1.5.6.3] +* link:v1.5.6.4/git.html[documentation for release 1.5.6.4] * release notes for - link:RelNotes-1.5.6.3.txt[1.5.6.3]. - link:RelNotes-1.5.6.2.txt[1.5.6.2]. - link:RelNotes-1.5.6.1.txt[1.5.6.1]. + link:RelNotes-1.5.6.4.txt[1.5.6.4], + link:RelNotes-1.5.6.3.txt[1.5.6.3], + link:RelNotes-1.5.6.2.txt[1.5.6.2], + link:RelNotes-1.5.6.1.txt[1.5.6.1], link:RelNotes-1.5.6.txt[1.5.6]. * link:v1.5.5.4/git.html[documentation for release 1.5.5.4] diff --git a/gitignore.html b/gitignore.html index 3c8799bc6..9f0bd936d 100644 --- a/gitignore.html +++ b/gitignore.html @@ -325,9 +325,14 @@ gitignore(5) Manual Page

    DESCRIPTION

    A gitignore file specifies intentionally untracked files that -git should ignore. Each line in a gitignore file specifies a -pattern.

    -

    When deciding whether to ignore a path, git normally checks +git should ignore. +Note that all the gitignore files really concern only files +that are not already tracked by git; +in order to ignore uncommitted changes in already tracked files, +please refer to the git update-index --assume-unchanged +documentation.

    +

    Each line in a gitignore file specifies a pattern. +When deciding whether to ignore a path, git normally checks gitignore patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of precedence, the last matching pattern decides the outcome):

    @@ -481,7 +486,7 @@ Frank Lichtenheld, and the git-list <git@vger.kernel.org>.

    diff --git a/gitignore.txt b/gitignore.txt index fc0efd8ec..59321a2e8 100644 --- a/gitignore.txt +++ b/gitignore.txt @@ -13,9 +13,14 @@ DESCRIPTION ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. - +git should ignore. +Note that all the `gitignore` files really concern only files +that are not already tracked by git; +in order to ignore uncommitted changes in already tracked files, +please refer to the 'git update-index --assume-unchanged' +documentation. + +Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks `gitignore` patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of diff --git a/technical/api-run-command.html b/technical/api-run-command.html index f4f555500..acbc32312 100644 --- a/technical/api-run-command.html +++ b/technical/api-run-command.html @@ -3,7 +3,7 @@ - + run-command API @@ -263,17 +311,17 @@ div.exampleblock-content {
    -

    The run-command API offers a versatile tool to run sub-processes with +

    The run-command API offers a versatile tool to run sub-processes with redirected input and output as well as with a modified environment -and an alternate current directory.

    -

    A similar API offers the capability to run a function asynchronously, +and an alternate current directory.

    +

    A similar API offers the capability to run a function asynchronously, which is primarily used to capture the output that the function -produces in the caller in order to process it.

    +produces in the caller in order to process it.

    -

    Functions

    +

    Functions

    -
    +
    start_command
    @@ -304,7 +352,7 @@ produces in the caller in order to process it.

    -run_command_v_opt, run_command_v_opt_dir, run_command_v_opt_cd_env +run_command_v_opt, run_command_v_opt_cd, run_command_v_opt_cd_env

    @@ -337,21 +385,21 @@ produces in the caller in order to process it.

    started with start_async().

    -
    +
    -

    Data structures

    +

    Data structures

    -
      +

      • struct child_process

        • -
      -

      This describes the arguments, redirections, and environment of a -command to run in a sub-process.

      -

      The caller:

      -
        +
    +

    This describes the arguments, redirections, and environment of a +command to run in a sub-process.

    +

    The caller:

    +

    1. allocates and clears (memset(&chld, 0, sizeof(chld));) a @@ -383,14 +431,14 @@ closes file descriptors (if necessary; see below); calls finish_command().

      2. -
    -

    The .argv member is set up as an array of string pointers (NULL +

    +

    The .argv member is set up as an array of string pointers (NULL terminated), of which .argv[0] is the program name to run (usually without a path). If the command to run is a git command, set argv[0] to -the command name without the git- prefix and set .git_cmd = 1.

    -

    The members .in, .out, .err are used to redirect stdin, stdout, -stderr as follows:

    -
      +the command name without the git- prefix and set .git_cmd = 1.

    +

    The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows:

    +

    1. Specify 0 to request no special redirection. No new file descriptor @@ -454,10 +502,10 @@ Special forms of redirection are available by setting these members redirected.

    - -

    To modify the environment of the sub-process, specify an array of -string pointers (NULL terminated) in .env:

    -
      +
    +

    To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env:

    +

    1. If the string is of the form "VAR=value", i.e. it contains = @@ -470,20 +518,20 @@ If the string does not contain =, it names an environment variable that will be removed from the child process's environment.

      2. -
    -

    To specify a new initial working directory for the sub-process, -specify it in the .dir member.

    -
      +
    +

    To specify a new initial working directory for the sub-process, +specify it in the .dir member.

    +

    • struct async

      • -
    -

    This describes a function to run asynchronously, whose purpose is -to produce output that the caller reads.

    -

    The caller:

    -
      +
    +

    This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads.

    +

    The caller:

    +

    1. allocates and clears (memset(&asy, 0, sizeof(asy));) a @@ -515,13 +563,13 @@ closes .out; calls finish_async().

      2. -
    -

    The function pointer in .proc has the following signature:

    +
    +

    The function pointer in .proc has the following signature:

    int proc(int fd, void *data);
    -
      +

      1. fd specifies a writable file descriptor to which the function must @@ -542,11 +590,11 @@ The return value of the function is 0 on success and non-zero report failure as well.

        2. -
      -

      There are serious restrictions on what the asynchronous function can do +

    +

    There are serious restrictions on what the asynchronous function can do because this facility is implemented by a pipe to a forked process on -UNIX, but by a thread in the same address space on Windows:

    -
      +UNIX, but by a thread in the same address space on Windows:

    +

    1. It cannot change the program's state (global variables, environment, @@ -560,11 +608,11 @@ It must not change the program's state that the caller of the facility also uses.

      2. -
    +
    diff --git a/technical/api-run-command.txt b/technical/api-run-command.txt index 3e1342acf..75aa5d492 100644 --- a/technical/api-run-command.txt +++ b/technical/api-run-command.txt @@ -30,7 +30,7 @@ Functions start_command() followed by finish_command(). Takes a pointer to a `struct child_process` that specifies the details. -`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: +`run_command_v_opt`, `run_command_v_opt_cd`, `run_command_v_opt_cd_env`:: Convenience functions that encapsulate a sequence of start_command() followed by finish_command(). The argument argv -- 2.26.2