3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Contextual diffing.
26 * This is an internalized library for performing contextual diffs
27 * between sources of data.
29 * @note This is different than Subversion's binary-diffing engine.
30 * That API lives in @c svn_delta.h -- see the "text deltas" section. A
31 * "text delta" is way of representing precise binary diffs between
32 * strings of data. The Subversion client and server send text deltas
33 * to one another during updates and commits.
35 * This API, however, is (or will be) used for performing *contextual*
36 * merges between files in the working copy. During an update or
37 * merge, 3-way file merging is needed. And 'svn diff' needs to show
38 * the differences between 2 files.
40 * The nice thing about this API is that it's very general. It
41 * operates on any source of data (a "datasource") and calculates
42 * contextual differences on "tokens" within the data. In our
43 * particular usage, the datasources are files and the tokens are
44 * lines. But the possibilities are endless.
52 #include <apr_pools.h>
53 #include <apr_tables.h> /* for apr_array_header_t */
55 #include "svn_types.h"
56 #include "svn_io.h" /* for svn_stream_t */
57 #include "svn_string.h"
58 #include "svn_mergeinfo.h"
62 #endif /* __cplusplus */
67 * Get libsvn_diff version information.
72 svn_diff_version(void);
77 /** An opaque type that represents a difference between either two or
78 * three datasources. This object is returned by svn_diff_diff(),
79 * svn_diff_diff3() and svn_diff_diff4(), and consumed by a number of
82 typedef struct svn_diff_t svn_diff_t;
85 * There are four types of datasources. In GNU diff3 terminology,
86 * the first three types correspond to the phrases "older", "mine",
89 typedef enum svn_diff_datasource_e
91 /** The oldest form of the data. */
92 svn_diff_datasource_original,
94 /** The same data, but potentially changed by the user. */
95 svn_diff_datasource_modified,
97 /** The latest version of the data, possibly different than the
98 * user's modified version.
100 svn_diff_datasource_latest,
102 /** The common ancestor of original and modified. */
103 svn_diff_datasource_ancestor
105 } svn_diff_datasource_e;
108 /** A vtable for reading data from the three datasources.
109 * @since New in 1.7. */
110 typedef struct svn_diff_fns2_t
112 /** Open the datasources of type @a datasources. */
113 svn_error_t *(*datasources_open)(void *diff_baton,
114 apr_off_t *prefix_lines,
115 apr_off_t *suffix_lines,
116 const svn_diff_datasource_e *datasources,
117 apr_size_t datasources_len);
119 /** Close the datasource of type @a datasource. */
120 svn_error_t *(*datasource_close)(void *diff_baton,
121 svn_diff_datasource_e datasource);
123 /** Get the next "token" from the datasource of type @a datasource.
124 * Return a "token" in @a *token. Return a hash of "token" in @a *hash.
125 * Leave @a token and @a hash untouched when the datasource is exhausted.
127 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token,
129 svn_diff_datasource_e datasource);
131 /** A function for ordering the tokens, resembling 'strcmp' in functionality.
132 * @a compare should contain the return value of the comparison:
133 * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is
134 * "less than" @a rtoken, return a number < 0. If @a ltoken is
135 * "greater than" @a rtoken, return a number > 0.
137 svn_error_t *(*token_compare)(void *diff_baton,
142 /** Free @a token from memory, the diff algorithm is done with it. */
143 void (*token_discard)(void *diff_baton,
146 /** Free *all* tokens from memory, they're no longer needed. */
147 void (*token_discard_all)(void *diff_baton);
151 /** Like #svn_diff_fns2_t except with datasource_open() instead of
152 * datasources_open().
154 * @deprecated Provided for backward compatibility with the 1.6 API.
156 typedef struct svn_diff_fns_t
158 svn_error_t *(*datasource_open)(void *diff_baton,
159 svn_diff_datasource_e datasource);
161 svn_error_t *(*datasource_close)(void *diff_baton,
162 svn_diff_datasource_e datasource);
164 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token,
166 svn_diff_datasource_e datasource);
168 svn_error_t *(*token_compare)(void *diff_baton,
173 void (*token_discard)(void *diff_baton,
176 void (*token_discard_all)(void *diff_baton);
180 /* The Main Events */
182 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
183 * return a diff object in @a *diff that represents a difference between
184 * an "original" and "modified" datasource. Do all allocation in @a pool.
189 svn_diff_diff_2(svn_diff_t **diff,
191 const svn_diff_fns2_t *diff_fns,
194 /** Like svn_diff_diff_2() but using #svn_diff_fns_t instead of
197 * @deprecated Provided for backward compatibility with the 1.6 API.
201 svn_diff_diff(svn_diff_t **diff,
203 const svn_diff_fns_t *diff_fns,
206 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
207 * return a diff object in @a *diff that represents a difference between
208 * three datasources: "original", "modified", and "latest". Do all
209 * allocation in @a pool.
214 svn_diff_diff3_2(svn_diff_t **diff,
216 const svn_diff_fns2_t *diff_fns,
219 /** Like svn_diff_diff3_2() but using #svn_diff_fns_t instead of
222 * @deprecated Provided for backward compatibility with the 1.6 API.
226 svn_diff_diff3(svn_diff_t **diff,
228 const svn_diff_fns_t *diff_fns,
231 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
232 * return a diff object in @a *diff that represents a difference between
233 * two datasources: "original" and "latest", adjusted to become a full
234 * difference between "original", "modified" and "latest" using "ancestor".
235 * Do all allocation in @a pool.
240 svn_diff_diff4_2(svn_diff_t **diff,
242 const svn_diff_fns2_t *diff_fns,
245 /** Like svn_diff_diff4_2() but using #svn_diff_fns_t instead of
248 * @deprecated Provided for backward compatibility with the 1.6 API.
252 svn_diff_diff4(svn_diff_t **diff,
254 const svn_diff_fns_t *diff_fns,
258 /* Utility functions */
260 /** Determine if a diff object contains conflicts. If it does, return
261 * @c TRUE, else return @c FALSE.
264 svn_diff_contains_conflicts(svn_diff_t *diff);
267 /** Determine if a diff object contains actual differences between the
268 * datasources. If so, return @c TRUE, else return @c FALSE.
271 svn_diff_contains_diffs(svn_diff_t *diff);
276 /* Displaying Diffs */
278 /** A vtable for displaying (or consuming) differences between datasources.
280 * Differences, similarities, and conflicts are described by lining up
283 * Any of the function pointers in this vtable may be NULL to ignore the
284 * corresponding kinds of output.
286 * @note These callbacks describe data ranges in units of "tokens".
287 * A "token" is whatever you've defined it to be in your datasource
288 * @c svn_diff_fns_t vtable.
290 typedef struct svn_diff_output_fns_t
292 /* Two-way and three-way diffs both call the first two output functions: */
295 * If doing a two-way diff, then an *identical* data range was found
296 * between the "original" and "modified" datasources. Specifically,
297 * the match starts at @a original_start and goes for @a original_length
298 * tokens in the original data, and at @a modified_start for
299 * @a modified_length tokens in the modified data.
301 * If doing a three-way diff, then all three datasources have
302 * matching data ranges. The range @a latest_start, @a latest_length in
303 * the "latest" datasource is identical to the range @a original_start,
304 * @a original_length in the original data, and is also identical to
305 * the range @a modified_start, @a modified_length in the modified data.
307 svn_error_t *(*output_common)(void *output_baton,
308 apr_off_t original_start,
309 apr_off_t original_length,
310 apr_off_t modified_start,
311 apr_off_t modified_length,
312 apr_off_t latest_start,
313 apr_off_t latest_length);
316 * If doing a two-way diff, then an *conflicting* data range was found
317 * between the "original" and "modified" datasources. Specifically,
318 * the conflict starts at @a original_start and goes for @a original_length
319 * tokens in the original data, and at @a modified_start for
320 * @a modified_length tokens in the modified data.
322 * If doing a three-way diff, then an identical data range was discovered
323 * between the "original" and "latest" datasources, but this conflicts with
324 * a range in the "modified" datasource.
326 svn_error_t *(*output_diff_modified)(void *output_baton,
327 apr_off_t original_start,
328 apr_off_t original_length,
329 apr_off_t modified_start,
330 apr_off_t modified_length,
331 apr_off_t latest_start,
332 apr_off_t latest_length);
334 /* ------ The following callbacks are used by three-way diffs only --- */
336 /** An identical data range was discovered between the "original" and
337 * "modified" datasources, but this conflicts with a range in the
338 * "latest" datasource.
340 svn_error_t *(*output_diff_latest)(void *output_baton,
341 apr_off_t original_start,
342 apr_off_t original_length,
343 apr_off_t modified_start,
344 apr_off_t modified_length,
345 apr_off_t latest_start,
346 apr_off_t latest_length);
348 /** An identical data range was discovered between the "modified" and
349 * "latest" datasources, but this conflicts with a range in the
350 * "original" datasource.
352 svn_error_t *(*output_diff_common)(void *output_baton,
353 apr_off_t original_start,
354 apr_off_t original_length,
355 apr_off_t modified_start,
356 apr_off_t modified_length,
357 apr_off_t latest_start,
358 apr_off_t latest_length);
360 /** All three datasources have conflicting data ranges. The range
361 * @a latest_start, @a latest_length in the "latest" datasource conflicts
362 * with the range @a original_start, @a original_length in the "original"
363 * datasource, and also conflicts with the range @a modified_start,
364 * @a modified_length in the "modified" datasource.
365 * If there are common ranges in the "modified" and "latest" datasources
366 * in this conflicting range, @a resolved_diff will contain a diff
367 * which can be used to retrieve the common and conflicting ranges.
369 svn_error_t *(*output_conflict)(void *output_baton,
370 apr_off_t original_start,
371 apr_off_t original_length,
372 apr_off_t modified_start,
373 apr_off_t modified_length,
374 apr_off_t latest_start,
375 apr_off_t latest_length,
376 svn_diff_t *resolved_diff);
377 } svn_diff_output_fns_t;
379 /** Style for displaying conflicts during diff3 output.
383 typedef enum svn_diff_conflict_display_style_t
385 /** Display modified and latest, with conflict markers. */
386 svn_diff_conflict_display_modified_latest,
388 /** Like svn_diff_conflict_display_modified_latest, but with an
389 extra effort to identify common sequences between modified and
391 svn_diff_conflict_display_resolved_modified_latest,
393 /** Display modified, original, and latest, with conflict
395 svn_diff_conflict_display_modified_original_latest,
397 /** Just display modified, with no markers. */
398 svn_diff_conflict_display_modified,
400 /** Just display latest, with no markers. */
401 svn_diff_conflict_display_latest,
403 /** Like svn_diff_conflict_display_modified_original_latest, but
404 *only* showing conflicts. */
405 svn_diff_conflict_display_only_conflicts
407 /* IMPORTANT: If you extend this enum note that it is mapped in
408 tools/diff/diff3.c. */
409 } svn_diff_conflict_display_style_t;
412 /** Given a vtable of @a output_fns/@a output_baton for consuming
413 * differences, output the differences in @a diff.
415 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
416 * times while processing larger diffs.
421 svn_diff_output2(svn_diff_t *diff,
423 const svn_diff_output_fns_t *output_fns,
424 svn_cancel_func_t cancel_func,
427 /** Similar to svn_diff_output2(), but without cancel support.
429 * @deprecated Provided for backwards compatibility with the 1.8 API.
433 svn_diff_output(svn_diff_t *diff,
435 const svn_diff_output_fns_t *output_fns);
441 /** To what extent whitespace should be ignored when comparing lines.
445 typedef enum svn_diff_file_ignore_space_t
447 /** Ignore no whitespace. */
448 svn_diff_file_ignore_space_none,
450 /** Ignore changes in sequences of whitespace characters, treating each
451 * sequence of whitespace characters as a single space. */
452 svn_diff_file_ignore_space_change,
454 /** Ignore all whitespace characters. */
455 svn_diff_file_ignore_space_all
456 } svn_diff_file_ignore_space_t;
458 /** Options to control the behaviour of the file diff routines.
462 * @note This structure may be extended in the future, so to preserve binary
463 * compatibility, users must not allocate structs of this type themselves.
464 * @see svn_diff_file_options_create().
466 * @note Although its name suggests otherwise, this structure is used to
467 * pass options to file as well as in-memory diff functions.
469 typedef struct svn_diff_file_options_t
471 /** To what extent whitespace should be ignored when comparing lines.
472 * The default is @c svn_diff_file_ignore_space_none. */
473 svn_diff_file_ignore_space_t ignore_space;
474 /** Whether to treat all end-of-line markers the same when comparing lines.
475 * The default is @c FALSE. */
476 svn_boolean_t ignore_eol_style;
477 /** Whether the "@@" lines of the unified diff output should include a prefix
478 * of the nearest preceding line that starts with a character that might be
479 * the initial character of a C language identifier. The default is
483 svn_boolean_t show_c_function;
485 /** The number of context lines produced above and below modifications, if
486 * available. The number of context lines must be >= 0.
488 * @since New in 1.9 */
490 } svn_diff_file_options_t;
492 /** Allocate a @c svn_diff_file_options_t structure in @a pool, initializing
493 * it with default values.
497 svn_diff_file_options_t *
498 svn_diff_file_options_create(apr_pool_t *pool);
501 * Parse @a args, an array of <tt>const char *</tt> command line switches
502 * and adjust @a options accordingly. @a options is assumed to be initialized
503 * with default values. @a pool is used for temporary allocation.
507 * The following options are supported:
508 * - --ignore-space-change, -b
509 * - --ignore-all-space, -w
510 * - --ignore-eol-style
511 * - --show-c-function, -p @since New in 1.5.
512 * - --context, -U ARG @since New in 1.9.
513 * - --unified, -u (for compatibility, does nothing).
516 svn_diff_file_options_parse(svn_diff_file_options_t *options,
517 const apr_array_header_t *args,
521 /** A convenience function to produce a diff between two files.
525 * Return a diff object in @a *diff (allocated from @a pool) that represents
526 * the difference between an @a original file and @a modified file.
527 * (The file arguments must be full paths to the files.)
529 * Compare lines according to the relevant fields of @a options.
532 svn_diff_file_diff_2(svn_diff_t **diff,
533 const char *original,
534 const char *modified,
535 const svn_diff_file_options_t *options,
538 /** Similar to svn_file_diff_2(), but with @a options set to a struct with
541 * @deprecated Provided for backwards compatibility with the 1.3 API.
545 svn_diff_file_diff(svn_diff_t **diff,
546 const char *original,
547 const char *modified,
550 /** A convenience function to produce a diff between three files.
554 * Return a diff object in @a *diff (allocated from @a pool) that represents
555 * the difference between an @a original file, @a modified file, and @a latest
558 * Compare lines according to the relevant fields of @a options.
561 svn_diff_file_diff3_2(svn_diff_t **diff,
562 const char *original,
563 const char *modified,
565 const svn_diff_file_options_t *options,
568 /** Similar to svn_diff_file_diff3_2(), but with @a options set to a struct
569 * with default options.
571 * @deprecated Provided for backwards compatibility with the 1.3 API.
575 svn_diff_file_diff3(svn_diff_t **diff,
576 const char *original,
577 const char *modified,
581 /** A convenience function to produce a diff between four files.
585 * Return a diff object in @a *diff (allocated from @a pool) that represents
586 * the difference between an @a original file, @a modified file, @a latest
587 * and @a ancestor file. (The file arguments must be full paths to the files.)
589 * Compare lines according to the relevant fields of @a options.
592 svn_diff_file_diff4_2(svn_diff_t **diff,
593 const char *original,
594 const char *modified,
596 const char *ancestor,
597 const svn_diff_file_options_t *options,
600 /** Similar to svn_file_diff4_2(), but with @a options set to a struct with
603 * @deprecated Provided for backwards compatibility with the 1.3 API.
607 svn_diff_file_diff4(svn_diff_t **diff,
608 const char *original,
609 const char *modified,
611 const char *ancestor,
614 /** A convenience function to produce unified diff output from the
615 * diff generated by svn_diff_file_diff().
617 * Output a @a diff between @a original_path and @a modified_path in unified
618 * context diff format to @a output_stream. Optionally supply
619 * @a original_header and/or @a modified_header to be displayed in the header
620 * of the output. If @a original_header or @a modified_header is @c NULL, a
621 * default header will be displayed, consisting of path and last modified time.
622 * Output all headers and markers in @a header_encoding. If @a relative_to_dir
623 * is not @c NULL, the @a original_path and @a modified_path will have the
624 * @a relative_to_dir stripped from the front of the respective paths. If
625 * @a relative_to_dir is @c NULL, paths will be not be modified. If
626 * @a relative_to_dir is not @c NULL but @a relative_to_dir is not a parent
627 * path of the target, an error is returned. Finally, if @a relative_to_dir
628 * is a URL, an error will be returned.
630 * If @a context_size is not negative, then this number of context lines
631 * will be used in the generated diff output. Otherwise the legacy compile
632 * time default will be used.
634 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
635 * times while processing larger diffs.
640 svn_diff_file_output_unified4(svn_stream_t *output_stream,
642 const char *original_path,
643 const char *modified_path,
644 const char *original_header,
645 const char *modified_header,
646 const char *header_encoding,
647 const char *relative_to_dir,
648 svn_boolean_t show_c_function,
650 svn_cancel_func_t cancel_func,
652 apr_pool_t *scratch_pool);
654 /** Similar to svn_diff_file_output_unified4(), but without cancel
655 * support and with @a context_size set to -1.
658 * @deprecated Provided for backwards compatibility with the 1.8 API.
662 svn_diff_file_output_unified3(svn_stream_t *output_stream,
664 const char *original_path,
665 const char *modified_path,
666 const char *original_header,
667 const char *modified_header,
668 const char *header_encoding,
669 const char *relative_to_dir,
670 svn_boolean_t show_c_function,
673 /** Similar to svn_diff_file_output_unified3(), but with @a relative_to_dir
674 * set to NULL and @a show_c_function to false.
676 * @deprecated Provided for backwards compatibility with the 1.4 API.
680 svn_diff_file_output_unified2(svn_stream_t *output_stream,
682 const char *original_path,
683 const char *modified_path,
684 const char *original_header,
685 const char *modified_header,
686 const char *header_encoding,
689 /** Similar to svn_diff_file_output_unified2(), but with @a header_encoding
690 * set to @c APR_LOCALE_CHARSET.
692 * @deprecated Provided for backward compatibility with the 1.2 API.
696 svn_diff_file_output_unified(svn_stream_t *output_stream,
698 const char *original_path,
699 const char *modified_path,
700 const char *original_header,
701 const char *modified_header,
705 /** A convenience function to produce diff3 output from the
706 * diff generated by svn_diff_file_diff3().
708 * Output a @a diff between @a original_path, @a modified_path and
709 * @a latest_path in merged format to @a output_stream. Optionally supply
710 * @a conflict_modified, @a conflict_original, @a conflict_separator and/or
711 * @a conflict_latest to be displayed as conflict markers in the output.
712 * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or
713 * @a conflict_separator is @c NULL, a default marker will be displayed.
714 * @a conflict_style dictates how conflicts are displayed.
715 * Uses @a scratch_pool for temporary allocations.
717 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
718 * times while processing larger diffs.
723 svn_diff_file_output_merge3(svn_stream_t *output_stream,
725 const char *original_path,
726 const char *modified_path,
727 const char *latest_path,
728 const char *conflict_original,
729 const char *conflict_modified,
730 const char *conflict_latest,
731 const char *conflict_separator,
732 svn_diff_conflict_display_style_t conflict_style,
733 svn_cancel_func_t cancel_func,
735 apr_pool_t *scratch_pool);
737 /** Similar to svn_diff_file_output_merge3, but without cancel support.
741 * @deprecated Provided for backward compatibility with the 1.8 API.
745 svn_diff_file_output_merge2(svn_stream_t *output_stream,
747 const char *original_path,
748 const char *modified_path,
749 const char *latest_path,
750 const char *conflict_original,
751 const char *conflict_modified,
752 const char *conflict_latest,
753 const char *conflict_separator,
754 svn_diff_conflict_display_style_t conflict_style,
758 /** Similar to svn_diff_file_output_merge2, but with @a
759 * display_original_in_conflict and @a display_resolved_conflicts
760 * booleans instead of the @a conflict_style enum.
762 * If both booleans are false, acts like
763 * svn_diff_conflict_display_modified_latest; if @a
764 * display_original_in_conflict is true, acts like
765 * svn_diff_conflict_display_modified_original_latest; if @a
766 * display_resolved_conflicts is true, acts like
767 * svn_diff_conflict_display_resolved_modified_latest. The booleans
768 * may not both be true.
770 * @deprecated Provided for backward compatibility with the 1.5 API.
774 svn_diff_file_output_merge(svn_stream_t *output_stream,
776 const char *original_path,
777 const char *modified_path,
778 const char *latest_path,
779 const char *conflict_original,
780 const char *conflict_modified,
781 const char *conflict_latest,
782 const char *conflict_separator,
783 svn_boolean_t display_original_in_conflict,
784 svn_boolean_t display_resolved_conflicts,
787 /** Creates a git-like binary diff hunk describing the differences between
788 * @a original and @a latest. It does this by either producing either the
789 * literal content of both versions in a compressed format, or by describing
790 * one way transforms.
792 * Either @a original or @a latest may be NULL to describe that the version
795 * Writes the output to @a output_stream.
797 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
798 * times while processing larger diffs.
803 svn_diff_output_binary(svn_stream_t *output_stream,
804 svn_stream_t *original,
805 svn_stream_t *latest,
806 svn_cancel_func_t cancel_func,
808 apr_pool_t *scratch_pool);
810 /* Diffs on in-memory structures */
812 /** Generate @a diff output from the @a original and @a modified
813 * in-memory strings. @a diff will be allocated from @a pool.
818 svn_diff_mem_string_diff(svn_diff_t **diff,
819 const svn_string_t *original,
820 const svn_string_t *modified,
821 const svn_diff_file_options_t *options,
825 /** Generate @a diff output from the @a original, @a modified and @a latest
826 * in-memory strings. @a diff will be allocated in @a pool.
831 svn_diff_mem_string_diff3(svn_diff_t **diff,
832 const svn_string_t *original,
833 const svn_string_t *modified,
834 const svn_string_t *latest,
835 const svn_diff_file_options_t *options,
839 /** Generate @a diff output from the @a original, @a modified and @a latest
840 * in-memory strings, using @a ancestor. @a diff will be allocated in @a pool.
845 svn_diff_mem_string_diff4(svn_diff_t **diff,
846 const svn_string_t *original,
847 const svn_string_t *modified,
848 const svn_string_t *latest,
849 const svn_string_t *ancestor,
850 const svn_diff_file_options_t *options,
853 /** Outputs the @a diff object generated by svn_diff_mem_string_diff()
854 * in unified diff format on @a output_stream, using @a original
855 * and @a modified for the text in the output.
857 * If @a with_diff_header is TRUE, write a diff header ("---" and "+++"
858 * lines), using @a original_header and @a modified_header to fill the field
859 * after the "---" and "+++" markers; otherwise @a original_header and
860 * @a modified_header are ignored and may be NULL.
862 * Outputs the header and hunk delimiters in @a header_encoding.
863 * A @a hunk_delimiter can optionally be specified.
864 * If @a hunk_delimiter is NULL, use the default hunk delimiter "@@".
866 * As a special case, if the hunk delimiter is "##", then for an incomplete
867 * final line use the text "\ No newline at end of property" instead of
868 * "\ No newline at end of file".
870 * If @a context_size is not negative, then this number of context lines
871 * will be used in the generated diff output. Otherwise the legacy compile
872 * time default will be used.
874 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
875 * times while processing larger diffs.
877 * Uses @a scratch_pool for temporary allocations.
882 svn_diff_mem_string_output_unified3(svn_stream_t *output_stream,
884 svn_boolean_t with_diff_header,
885 const char *hunk_delimiter,
886 const char *original_header,
887 const char *modified_header,
888 const char *header_encoding,
889 const svn_string_t *original,
890 const svn_string_t *modified,
892 svn_cancel_func_t cancel_func,
894 apr_pool_t *scratch_pool);
896 /** Similar to svn_diff_mem_string_output_unified3() but without
897 * cancel support and with @a context_size set to -1.
899 * @since New in 1.7. Hunk delimiter "##" has the special meaning since 1.8.
901 * @deprecated Provided for backwards compatibility with the 1.8 API.
905 svn_diff_mem_string_output_unified2(svn_stream_t *output_stream,
907 svn_boolean_t with_diff_header,
908 const char *hunk_delimiter,
909 const char *original_header,
910 const char *modified_header,
911 const char *header_encoding,
912 const svn_string_t *original,
913 const svn_string_t *modified,
916 /** Similar to svn_diff_mem_string_output_unified2() but with
917 * @a with_diff_header always set to TRUE and @a hunk_delimiter always
922 * @deprecated Provided for backwards compatibility with the 1.8 API.
926 svn_diff_mem_string_output_unified(svn_stream_t *output_stream,
928 const char *original_header,
929 const char *modified_header,
930 const char *header_encoding,
931 const svn_string_t *original,
932 const svn_string_t *modified,
935 /** Output the @a diff generated by svn_diff_mem_string_diff3() in diff3
936 * format on @a output_stream, using @a original, @a modified and @a latest
937 * for content changes.
939 * Use the conflict markers @a conflict_original, @a conflict_modified,
940 * @a conflict_latest and @a conflict_separator or the default one for
941 * each of these if @c NULL is passed.
943 * @a conflict_style dictates how conflicts are displayed.
945 * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
946 * times while processing larger diffs.
948 * Uses @a scratch_pool for temporary allocations.
953 svn_diff_mem_string_output_merge3(svn_stream_t *output_stream,
955 const svn_string_t *original,
956 const svn_string_t *modified,
957 const svn_string_t *latest,
958 const char *conflict_original,
959 const char *conflict_modified,
960 const char *conflict_latest,
961 const char *conflict_separator,
962 svn_diff_conflict_display_style_t style,
963 svn_cancel_func_t cancel_func,
965 apr_pool_t *scratch_pool);
967 /** Similar to svn_diff_mem_string_output_merge2(), but without cancel support.
971 * @deprecated Provided for backwards compatibility with the 1.8 API.
975 svn_diff_mem_string_output_merge2(svn_stream_t *output_stream,
977 const svn_string_t *original,
978 const svn_string_t *modified,
979 const svn_string_t *latest,
980 const char *conflict_original,
981 const char *conflict_modified,
982 const char *conflict_latest,
983 const char *conflict_separator,
984 svn_diff_conflict_display_style_t style,
987 /** Similar to svn_diff_mem_string_output_merge2, but with @a
988 * display_original_in_conflict and @a display_resolved_conflicts
989 * booleans instead of the @a conflict_style enum.
991 * If both booleans are false, acts like
992 * svn_diff_conflict_display_modified_latest; if @a
993 * display_original_in_conflict is true, acts like
994 * svn_diff_conflict_display_modified_original_latest; if @a
995 * display_resolved_conflicts is true, acts like
996 * svn_diff_conflict_display_resolved_modified_latest. The booleans
997 * may not both be true.
999 * @deprecated Provided for backward compatibility with the 1.5 API.
1003 svn_diff_mem_string_output_merge(svn_stream_t *output_stream,
1005 const svn_string_t *original,
1006 const svn_string_t *modified,
1007 const svn_string_t *latest,
1008 const char *conflict_original,
1009 const char *conflict_modified,
1010 const char *conflict_latest,
1011 const char *conflict_separator,
1012 svn_boolean_t display_original_in_conflict,
1013 svn_boolean_t display_resolved_conflicts,
1018 /* Diff parsing. If you want to apply a patch to a working copy
1019 * rather than parse it, see svn_client_patch(). */
1022 * Describes what operation has been performed on a file.
1024 * @since New in 1.7.
1026 typedef enum svn_diff_operation_kind_e
1028 svn_diff_op_unchanged,
1030 svn_diff_op_deleted,
1033 /* There's no tree changes, just text modifications. */
1034 svn_diff_op_modified
1035 } svn_diff_operation_kind_t;
1038 * A single hunk inside a patch.
1040 * The lines of text comprising the hunk can be interpreted in three ways:
1041 * - diff text The hunk as it appears in the unidiff patch file,
1042 * including the hunk header line ("@@ ... @@")
1043 * - original text The text the patch was based on.
1044 * - modified text The result of patching the original text.
1046 * For example, consider a hunk with the following diff text:
1051 int main(int argc, char *argv[]) {
1052 - printf("Hello World!\n");
1053 + printf("I like Subversion!\n");
1056 * The original text of this hunk is:
1060 int main(int argc, char *argv[]) {
1061 printf("Hello World!\n");
1064 * And the modified text is:
1068 int main(int argc, char *argv[]) {
1069 printf("I like Subversion!\n");
1072 * @see svn_diff_hunk_readline_diff_text()
1073 * @see svn_diff_hunk_readline_original_text()
1074 * @see svn_diff_hunk_readline_modified_text()
1076 * @since New in 1.7. */
1077 typedef struct svn_diff_hunk_t svn_diff_hunk_t;
1080 * Allocate @a *stringbuf in @a result_pool, and read into it one line
1081 * of the diff text of @a hunk. The hunk header is not returned only the
1082 * unidiff data lines (starting with '+', '-', or ' ') are returned.
1083 * If the @a hunk is being interpreted in reverse (i.e. the reverse
1084 * parameter of svn_diff_parse_next_patch() was @c TRUE), the diff
1085 * text will be returned in reversed form.
1086 * The line-terminator is detected automatically and stored in @a *eol
1087 * if @a eol is not NULL.
1088 * If EOF is reached, set @a *eof to TRUE, and set @a *eol to NULL if the
1089 * hunk does not end with a newline character and @a eol is not NULL.
1090 * Temporary allocations will be performed in @a scratch_pool.
1092 * @note The hunk header information can be retrieved with the following
1094 * @see svn_diff_hunk_get_original_start()
1095 * @see svn_diff_hunk_get_original_length()
1096 * @see svn_diff_hunk_get_modified_start()
1097 * @see svn_diff_hunk_get_modified_length()
1099 * @since New in 1.7.
1102 svn_diff_hunk_readline_diff_text(svn_diff_hunk_t *hunk,
1103 svn_stringbuf_t **stringbuf,
1106 apr_pool_t *result_pool,
1107 apr_pool_t *scratch_pool);
1110 * Allocate @a *stringbuf in @a result_pool, and read into it one line
1111 * of the original text of @a hunk.
1112 * The line-terminator is detected automatically and stored in @a *eol
1113 * if @a eol is not NULL.
1114 * If EOF is reached, set @a *eof to TRUE, and set @a *eol to NULL if the
1115 * hunk text does not end with a newline character and @a eol is not NULL.
1116 * Temporary allocations will be performed in @a scratch_pool.
1118 * @see svn_diff_hunk_t
1119 * @since New in 1.7.
1122 svn_diff_hunk_readline_original_text(svn_diff_hunk_t *hunk,
1123 svn_stringbuf_t **stringbuf,
1126 apr_pool_t *result_pool,
1127 apr_pool_t *scratch_pool);
1130 * Like svn_diff_hunk_readline_original_text(), but it returns lines from
1131 * the modified text of the hunk.
1133 * @see svn_diff_hunk_t
1134 * @since New in 1.7.
1137 svn_diff_hunk_readline_modified_text(svn_diff_hunk_t *hunk,
1138 svn_stringbuf_t **stringbuf,
1141 apr_pool_t *result_pool,
1142 apr_pool_t *scratch_pool);
1144 /** Reset the diff text of @a hunk so it can be read again from the start.
1145 * @since New in 1.7. */
1147 svn_diff_hunk_reset_diff_text(svn_diff_hunk_t *hunk);
1149 /** Reset the original text of @a hunk so it can be read again from the start.
1150 * @since New in 1.7. */
1152 svn_diff_hunk_reset_original_text(svn_diff_hunk_t *hunk);
1154 /** Reset the modified text of @a hunk so it can be read again from the start.
1155 * @since New in 1.7. */
1157 svn_diff_hunk_reset_modified_text(svn_diff_hunk_t *hunk);
1159 /** Return the line offset of the original hunk text,
1160 * as parsed from the hunk header.
1161 * @since New in 1.7. */
1163 svn_diff_hunk_get_original_start(const svn_diff_hunk_t *hunk);
1165 /** Return the number of lines in the original @a hunk text,
1166 * as parsed from the hunk header.
1167 * @since New in 1.7. */
1169 svn_diff_hunk_get_original_length(const svn_diff_hunk_t *hunk);
1171 /** Return the line offset of the modified @a hunk text,
1172 * as parsed from the hunk header.
1173 * @since New in 1.7. */
1175 svn_diff_hunk_get_modified_start(const svn_diff_hunk_t *hunk);
1177 /** Return the number of lines in the modified @a hunk text,
1178 * as parsed from the hunk header.
1179 * @since New in 1.7. */
1181 svn_diff_hunk_get_modified_length(const svn_diff_hunk_t *hunk);
1183 /** Return the number of lines of leading context of @a hunk,
1184 * i.e. the number of lines starting with ' ' before the first line
1185 * that starts with a '+' or '-'.
1186 * @since New in 1.7. */
1188 svn_diff_hunk_get_leading_context(const svn_diff_hunk_t *hunk);
1190 /** Return the number of lines of trailing context of @a hunk,
1191 * i.e. the number of lines starting with ' ' after the last line
1192 * that starts with a '+' or '-'.
1193 * @since New in 1.7. */
1195 svn_diff_hunk_get_trailing_context(const svn_diff_hunk_t *hunk);
1198 * Data type to manage parsing of properties in patches.
1199 * API users should not allocate structures of this type directly.
1201 * @since New in 1.7. */
1202 typedef struct svn_prop_patch_t {
1205 /** Represents the operation performed on the property */
1206 svn_diff_operation_kind_t operation;
1209 * An array containing an svn_diff_hunk_t object for each hunk parsed
1210 * from the patch associated with our property name */
1211 apr_array_header_t *hunks;
1215 * A binary patch representation. This basically describes replacing one
1216 * exact binary representation with another one.
1218 * @since New in 1.10. */
1219 typedef struct svn_diff_binary_patch_t svn_diff_binary_patch_t;
1222 * Creates a stream allocated in @a result_pool from which the original
1223 * (pre-patch-application) version of the binary patched file can be read.
1225 * @note Like many svn_diff_get functions over patches, this is implemented
1226 * as reading from the backing patch file. Therefore it is recommended to
1227 * read the whole stream before using other functions on the same patch file.
1229 * @since New in 1.10 */
1231 svn_diff_get_binary_diff_original_stream(const svn_diff_binary_patch_t *bpatch,
1232 apr_pool_t *result_pool);
1235 * Creates a stream allocated in @a result_pool from which the resulting
1236 * (post-patch-application) version of the binary patched file can be read.
1238 * @note Like many svn_diff_get functions over patches, this is implemented
1239 * as reading from the backing patch file. Therefore it is recommended to
1240 * read the whole stream before using other functions on the same patch file.
1242 * @since New in 1.10 */
1244 svn_diff_get_binary_diff_result_stream(const svn_diff_binary_patch_t *bpatch,
1245 apr_pool_t *result_pool);
1248 * Data type to manage parsing of patches.
1250 * Represents a patch to one target file.
1252 * API users should not allocate structures of this type directly.
1254 * @since New in 1.7. */
1255 typedef struct svn_patch_t {
1257 * The old and new file names as retrieved from the patch file.
1258 * These paths are UTF-8 encoded and canonicalized, but otherwise
1259 * left unchanged from how they appeared in the patch file. */
1260 const char *old_filename;
1261 const char *new_filename;
1264 * An array containing an svn_diff_hunk_t * for each hunk parsed
1265 * from the patch. */
1266 apr_array_header_t *hunks;
1269 * A hash table keyed by property names containing svn_prop_patch_t
1270 * object for each property parsed from the patch. */
1271 apr_hash_t *prop_patches;
1274 * Represents the operation performed on the file. */
1275 svn_diff_operation_kind_t operation;
1278 * Indicates whether the patch is being interpreted in reverse.
1279 * ### If so, how does this affect the interpretation of other fields?
1281 svn_boolean_t reverse;
1284 * Mergeinfo parsed from svn:mergeinfo diff data, with one entry for
1285 * forward merges and one for reverse merges.
1286 * Either entry can be @c NULL if no such merges are part of the diff.
1287 * @since New in 1.9. */
1288 svn_mergeinfo_t mergeinfo;
1289 svn_mergeinfo_t reverse_mergeinfo;
1292 * Declares that there is a binary conflict and contains the information
1293 * to apply it as parsed from the file.
1294 * @since New in 1.10. */
1295 svn_diff_binary_patch_t *binary_patch;
1297 /** The old and new executability bits, as retrieved from the patch file, from
1298 * the git-like mode headers.
1300 * A patch may specify an executability change via @a old_executable_bit and
1301 * @a new_executable_bit, via a #SVN_PROP_EXECUTABLE propchange hunk, or both
1302 * ways. It is upto caller how to decide how conflicting information is
1305 * #svn_tristate_unknown indicates the patch does not specify the
1306 * corresponding bit.
1308 * @since New in 1.10.
1310 svn_tristate_t old_executable_bit;
1311 svn_tristate_t new_executable_bit;
1313 /** The old and new symlink bits, as retrieved from the patch file, from
1314 * the git-like mode headers.
1316 * A patch may specify a symlink change via @a old_symlink_bit and
1317 * @a new_symlink_bit, via a #SVN_PROP_SPECIAL propchange hunk, or both
1318 * ways. It is upto caller how to decide how conflicting information is
1319 * handled. Most implementations will currently just describe a replacement
1320 * of the file though.
1322 * #svn_tristate_unknown indicates the patch does not specify the
1323 * corresponding bit.
1325 * @since New in 1.10.
1327 svn_tristate_t old_symlink_bit;
1328 svn_tristate_t new_symlink_bit;
1331 /** An opaque type representing an open patch file.
1333 * @since New in 1.7. */
1334 typedef struct svn_patch_file_t svn_patch_file_t;
1336 /** Open @a patch_file at @a local_abspath.
1337 * Allocate @a patch_file in @a result_pool.
1339 * @since New in 1.7. */
1341 svn_diff_open_patch_file(svn_patch_file_t **patch_file,
1342 const char *local_abspath,
1343 apr_pool_t *result_pool);
1346 * Return the next @a *patch in @a patch_file.
1347 * If no patch can be found, set @a *patch to NULL.
1348 * If @a reverse is TRUE, invert the patch while parsing it.
1349 * If @a ignore_whitespace is TRUE, allow patches with no leading
1350 * whitespace to be parsed.
1351 * Allocate results in @a result_pool.
1352 * Use @a scratch_pool for all other allocations.
1354 * @since New in 1.7. */
1356 svn_diff_parse_next_patch(svn_patch_t **patch,
1357 svn_patch_file_t *patch_file,
1358 svn_boolean_t reverse,
1359 svn_boolean_t ignore_whitespace,
1360 apr_pool_t *result_pool,
1361 apr_pool_t *scratch_pool);
1364 * Dispose of @a patch_file.
1365 * Use @a scratch_pool for all temporary allocations.
1367 * @since New in 1.7.
1370 svn_diff_close_patch_file(svn_patch_file_t *patch_file,
1371 apr_pool_t *scratch_pool);
1375 #endif /* __cplusplus */
1377 #endif /* SVN_DIFF_H */