The relationship between these makes more sense if you read
them as a group, which can help people who are looking for
the right function. Let's give them a single comment.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The description of strbuf_split_buf says most of what
needs to be said for all of the split variants that take
strings, raw memory, etc. We have a boilerplate comment
above each that points to the first. This boilerplate
ends up making it harder to read, because it spaces out the
functions, which could otherwise be read as a group.
Let's drop the boilerplate completely, and mention the
variants in the top comment. This is perhaps slightly worse
for a hypothetical system which pulls the documentation for
each function out of the comment immediately preceding it.
But such a system does not yet exist, and anyway, the end
result of extracting the boilerplate comments would not lead
to a very easy-to-read result. We would do better in the
long run to teach the extraction system about groups of
related functions.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The original API doc had something like:
Functions
---------
* Life cycle
... some life-cycle functions ...
* Related to the contents of the buffer
... functions related to contents ....
etc
This grouping can be hard to read in the comment sources,
given the "*" in the comment lines, and the amount of text
between each section.
Instead, let's make a flat list of groupings, and underline
each as a section header. That makes them stand out, and
eliminates the weird half-phrase of "Related to...". Like:
Functions related to the contents of the buffer
-----------------------------------------------
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This is much easier to read when the whole thing is stuffed
inside a comment block. And there is precedent for this
convention in markdown (and just in general ascii text).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Using a hanging indent is much more readable. This means we
won't format as asciidoc anymore, but since we don't have a
working system for extracting these comments anyway, it's
probably more important to just make the source readable.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The prior patch uses "/**" to denote "documentation"
comments that we pulled from api-strbuf.txt. Let's use a
consistent style for similar comments that were already in
strbuf.h.
Signed-off-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Some of strbuf is documented as comments above functions,
and some is separate in Documentation/technical/api-strbuf.txt.
This makes it annoying to find the appropriate documentation.
We'd rather have it all in one place, which means all in the
text document, or all in the header.
Let's choose the header as that place. Even though the
formatting is not quite as pretty, this keeps the
documentation close to the related code. The hope is that
this makes it easier to find what you want (human-readable
comments are right next to the C declarations), and easier
for writers to keep the documentation up to date.
This is more or less a straight import of the text from
api-strbuf.txt into C comments, complete with asciidoc
formatting. The exceptions are:
1. All comments created in this way are started with "/**"
to indicate they are part of the API documentation. This
may help later with extracting the text to pretty-print
it.
2. Function descriptions do not repeat the function name,
as it is available in the context directly below. So:
`strbuf_add`::
Add data of given length to the buffer.
from api-strbuf.txt becomes:
/**
* Add data of given length to the buffer.
*/
void strbuf_add(struct strbuf *sb, const void *, size_t);
As a result, any block-continuation required in asciidoc
for that list item was dropped in favor of straight
blank-line paragraph (since it is not necessary when we
are not in a list item).
3. There is minor re-wording to integrate existing comments
and api-strbuf text. In each case, I took whichever
version was more descriptive, and eliminated any
redundancies. In one case, for strbuf_addstr, the api
documentation gave its inline definition; I eliminated
this as redundant with the actual definition, which can
be seen directly below the comment.
4. The functions in the header file are re-ordered to match
the ordering of the API documentation, under the
assumption that more thought went into the grouping
there.
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Git 2.0 was supposed to make the "simple" mode for the default of
"git push", but it didn't.
* jk/push-simple:
push: truly use "simple" as default, not "upstream"
The build procedure did not bother fixing perl and python scripts
when NO_PERL and NO_PYTHON build-time configuration changed.
* jk/rebuild-perl-scripts-with-no-perl-seting-change:
Makefile: have python scripts depend on NO_PYTHON setting
Makefile: simplify by using SCRIPT_{PERL,SH}_GEN macros
Makefile: have perl scripts depend on NO_PERL setting
Some tests that depend on perl lacked PERL prerequisite to protect
them, breaking build with NO_PERL configuration.
* jk/no-perl-tests:
t960[34]: mark cvsimport tests as requiring perl
t0090: mark add-interactive test with PERL prerequisite
A request to store an empty note via "git notes" meant to remove
note from the object but with --allow-empty we will store a (surprise!)
note that is empty. In the longer run, we might want to deprecate
the somewhat unintuitive "emptying means deletion" behaviour.
* jh/empty-notes:
t3301: modernize style
notes: empty notes should be shown by 'git log'
builtin/notes: add --allow-empty, to allow storing empty notes
builtin/notes: split create_note() to clarify add vs. remove logic
builtin/notes: simplify early exit code in add()
builtin/notes: refactor note file path into struct note_data
builtin/notes: improve naming
t3301: verify that 'git notes' removes empty notes by default
builtin/notes: fix premature failure when trying to add the empty blob
"git checkout $treeish $path", when $path in the index and the
working tree already matched what is in $treeish at the $path,
still overwrote the $path unnecessarily.
* jk/checkout-from-tree:
checkout $tree: do not throw away unchanged index entries
Allow passing extra set of arguments when ssh is invoked to create
an encrypted & authenticated connection by introducing a new environment
variable GIT_SSH_COMMAND, whose contents is interpreted by shells.
This is not possible with existing GIT_SSH mechanism whose
invocation bypasses shells, which was designed more to match what
other programs with similar variables did, not necessarily to be
more useful.
* tq/git-ssh-command:
git_connect: set ssh shell command in GIT_SSH_COMMAND
The plan for the push.default transition had all along been
to use the "simple" method rather than "upstream" as a
default if the user did not specify their own push.default
value. Commit 11037ee (push: switch default from "matching"
to "simple", 2013-01-04) tried to implement that by moving
PUSH_DEFAULT_UNSPECIFIED in our switch statement to
fall-through to the PUSH_DEFAULT_SIMPLE case.
When the commit that became 11037ee was originally written,
that would have been enough. We would fall through to
calling setup_push_upstream() with the "simple" parameter
set to 1. However, it was delayed for a while until we were
ready to make the transition in Git 2.0.
And in the meantime, commit ed2b182 (push: change `simple`
to accommodate triangular workflows, 2013-06-19) threw a
monkey wrench into the works. That commit drops the "simple"
parameter to setup_push_upstream, and instead checks whether
the global "push_default" is PUSH_DEFAULT_SIMPLE. This is
right when the user has explicitly configured push.default
to simple, but wrong when we are a fall-through for the
"unspecified" case.
We never noticed because our push.default tests do not cover
the case of the variable being totally unset; they only
check the "simple" behavior itself.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "__attribute__" flag may be a noop on some compilers.
That's OK as long as the code is correct without the
attribute, but in this case it is not. We would typically
end up with a struct that is 2 bytes too long due to struct
padding, breaking both reading and writing of bitmaps.
Instead of marshalling the data in a struct, let's just
provide helpers for reading and writing the appropriate
types. Besides being correct on all platforms, the result is
more efficient and simpler to read.
Signed-off-by: Karsten Blees <blees@dcon.de>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
No callers rely on $status so there's don't need to set
it during merge_cmd() for diffmerge, emerge, and kdiff3.
Signed-off-by: David Aguilar <davvid@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Combine the $last_status checks into a single conditional.
Replace $last_status and $rollup_status with a single variable.
Signed-off-by: David Aguilar <davvid@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git-difftool--helper returns a zero exit status unless
--trust-exit-code is in effect. Add an explicit exit statement
to make this clearer.
Signed-off-by: David Aguilar <davvid@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove return statements and rework check_unchanged() so that the exit
status from the last evaluated expression bubbles up to the callers.
Signed-off-by: David Aguilar <davvid@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even though setup_user_tool assigns the exit status from "eval
$merge_tool_cmd" to $status, the variable is overwritten by the
function it calls next, check_unchanged, without ever getting looked
at by anybody. And "return $status" at the end of this function
returns the value check_unchanged assigned to it (which is the same
as the value the function returns). Which makes the assignment a
no-op.
Remove it.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If the user specifiers "normal" for a foreground color, this
should be a noop (while this may sound useless, it is the
only way to specify an unchanged foreground color followed
by a specific background color).
We also check that color "-1" does the same thing. This is
not documented, but has worked forever, so let's make sure
we keep supporting it.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Most of git-config's command line options use OPT_BIT to
choose an action, and then parse the non-option arguments
in a context-dependent way. However, --get-color and
--get-colorbool are unlike the rest of the options, in that
they are OPT_STRING, taking the option name as a parameter.
This generally works, because we then use the presence of
those strings to set an action bit anyway. But it does mean
that the option-parser will continue looking for options
even after the key (because it is not a non-option; it is an
argument to an option). And running:
git config --get-color some.key -1
(to use "-1" as the default color spec) will barf, claiming
that "-1" is not an option. Instead, we should treat
--get-color and --get-colorbool as action bits, just like
--add, --get, and all the other actions, and then check that
the non-option arguments we got are sane. This fixes the
weirdness above, and makes those two options like all the
others.
This "fixes" a test in t4026, which checked that feeding
"-2" as a color should fail (it does fail, but prior to this
patch, because parseopt barfed, not because we actually ever
tried to parse the color).
This also catches other errors, like:
git config --get-color some.key black blue
which previously silently ignored "blue" (and now will
complain that you gave too many arguments).
There are some possible regressions, though. We now disallow
these, which currently do what you would expect:
# specifying other options after the action
git config --get-color some.key --file whatever
# using long-arg syntax
git config --get-color=some.key
However, we have never advertised these in the
documentation, and in fact they did not work in some older
versions of git. The behavior was apparently switched as an
accidental side effect of d64ec16 (git config: reorganize to
use parseopt, 2009-02-21).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Our color specifications have supported the 256-color ANSI
extension for years, but we never documented it.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ralf reported that '--recurse-submodules' option in push.c should not be
translated [1]. Before his commit is merged, remove superfluous
translations for push.c.
[1] http://www.spinics.net/lists/git/msg241964.html
Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
