"Ciprian Dorin Craciun" [off-list ref] writes:
Is the function setup_git_directory_gently supposed to change the
current working directory, or should it keep the initial one?
What is the meaning of nongit_ok?
Most commands that work from subdirectory use setup_git_directory()
interface, because major parts of the guts of the git internal want you to
be at the top of the work tree (e.g. so that you grab a path out of the
index, and be able to open(2) or lstat(2) that path). A normal sequence
for a command is: (1) use setup_git_directory() to learn "prefix", (2) use
get_pathspec() and/or prefix_path() to add "prefix" to the paths given
from the command to make it a path relative to the work tree, (3) do its
thing. setup_git_directory() chdir's up to the top of the work tree for
this reason.
Some commands can optionally work from even outside a git repository, but
they would want to operate the same way as other comands, when they are
started within a git repository. In such a case, you use "gently"
variant, and give a pointer to int to store an additional return value to
signal you if you are inside a git repository or outside.
* When NULL is given as nongit_ok to gently(), it does not behave gentle
at all. Outside a git repository it dies loudly.
* If you are inside a git repository, it behaves pretty much the same as
setup_git_directory(). "*nongit_ok" is set to zero to signal that you
are inside a git repository.
* If you are outside a git repository, *nongit_ok is set to non-zero so
that the caller can tell that it is not in any git repository's work
tree. There is no need to chdir (nor a sensible place to chdir to) in
this case, so it doesn't.
The caller thinks of the parameter as "are we operating in non-git mode?"
boolean, and the callee (i.e. setup_git_directory_gently()) thinks of it
as "is it ok to be called outside a git repository?" (if it is NULL, the
caller expects to be inside a repository and wants it to barf otherwise).
That is why caller's variable are often called "int nongit", and the
callee's parameter is called "int *nongit_ok".
On Wed, May 28, 2008 at 1:46 AM, Junio C Hamano [off-list ref] wrote:
"Ciprian Dorin Craciun" [off-list ref] writes:
quoted
Is the function setup_git_directory_gently supposed to change the
current working directory, or should it keep the initial one?
What is the meaning of nongit_ok?
Most commands that work from subdirectory use setup_git_directory()
interface, because major parts of the guts of the git internal want you to
be at the top of the work tree (e.g. so that you grab a path out of the
index, and be able to open(2) or lstat(2) that path). A normal sequence
for a command is: (1) use setup_git_directory() to learn "prefix", (2) use
get_pathspec() and/or prefix_path() to add "prefix" to the paths given
from the command to make it a path relative to the work tree, (3) do its
thing. setup_git_directory() chdir's up to the top of the work tree for
this reason.
Some commands can optionally work from even outside a git repository, but
they would want to operate the same way as other comands, when they are
started within a git repository. In such a case, you use "gently"
variant, and give a pointer to int to store an additional return value to
signal you if you are inside a git repository or outside.
* When NULL is given as nongit_ok to gently(), it does not behave gentle
at all. Outside a git repository it dies loudly.
* If you are inside a git repository, it behaves pretty much the same as
setup_git_directory(). "*nongit_ok" is set to zero to signal that you
are inside a git repository.
* If you are outside a git repository, *nongit_ok is set to non-zero so
that the caller can tell that it is not in any git repository's work
tree. There is no need to chdir (nor a sensible place to chdir to) in
this case, so it doesn't.
The caller thinks of the parameter as "are we operating in non-git mode?"
boolean, and the callee (i.e. setup_git_directory_gently()) thinks of it
as "is it ok to be called outside a git repository?" (if it is NULL, the
caller expects to be inside a repository and wants it to barf otherwise).
That is why caller's variable are often called "int nongit", and the
callee's parameter is called "int *nongit_ok".
Thank you for your complete answer.
I would propose that these comments to be added to the
Documentation/technical/... directory, (or in the setup.c file), so
that further developers will have this information.
Thanks again,
Ciprian.