Once you've finished making changes, you need to commit them to the repository, but before you do so, it's usually a good idea to take a look at exactly what you've changed.
By examining your changes before you commit, you can compose a more accurate log message (a human-readable description of the committed changes stored alongside those changes in the repository).
You may also discover that you've inadvertently changed a file, and that you need to undo that change before committing.
Additionally, this is a good opportunity to review and scrutinize changes before publishing them.
You can see an overview of the changes you've made by using the
svn status
command, and you can dig into the details
of those changes by using the svn diff
command.
4.7.1 See an overview of your changes
To get an overview of your changes, use the svn status
command. You'll probably use svn status
more than any other Subversion command.
If you run svn status
at the top of your working copy with no additional arguments, it will detect and report all file and tree changes you've made.
$ svn status
? scratch.c
A stuff/loot
A stuff/loot/new.c
D stuff/old.c
M bar.c
$
In its default output mode,
svn status
prints seven columns of characters,
followed by several whitespace characters, followed by a file or directory name.
The first column tells the status of a file or directory and/or its contents.
Some of the most common codes that svn status
displays are:
? item
The file, directory, or symbolic link item is not under version control.
A item
The file, directory, or symbolic link item has been scheduled for addition into the repository.
C item
The file item is in a state of conflict. That is, changes received from the server during an update overlap with local changes that you have in your working copy (and weren't resolved during the update). You must resolve this conflict before committing your changes to the repository.
D item
The file, directory, or symbolic link item has been scheduled for deletion from the repository.
M item
The contents of the file item have been modified.
If you pass a specific path to svn status
, you get information about that item alone:
$ svn status stuff/fish.c
D stuff/fish.c
svn status
also has a --verbose
(-v
) option, which will show you the status of every item in your working copy, even if it has not been changed:
$ svn status -v
M 44 23 sally README
44 30 sally INSTALL
M 44 20 harry bar.c
44 18 ira stuff
44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
44 21 sally stuff/things
A 0 ? ? stuff/things/bloo.h
44 36 harry stuff/things/gloo.c
This is the long form output of svn status
. The letters in the first column mean the same as before, but the second column shows the working-revision of the item. The third and fourth columns show the revision in which the item last changed, and who changed it.
None of the prior invocations to svn status
contact the repository.
They merely report what is known about the working copy items based on the records stored in the working copy administrative area and on the timestamps and contents of modified files.
But sometimes it is useful to see which of the items in your working copy have been modified in the repository since the last time you updated your working copy.
For this, svn status
offers the --show-updates
(-u
) option, which contacts the repository and adds information about items that are out of date:
$ svn status -u -v
M * 44 23 sally README
M 44 20 harry bar.c
* 44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
A 0 ? ? stuff/things/bloo.h
Status against revision: 46
Notice in the previous example the two asterisks.
If you were to run svn update
at this point,
you would receive changes to README
and trout.c
.
This tells you some very useful information:
because one of those items is also one that you have locally modified
(the file README
),
you'll need to update and get the servers changes for that file before you commit,
or the repository will reject your commit for being out of date.
We discuss this in more detail later.
svn status
can display much more information about
the files and directories in your working copy than we've shown here.
For an exhaustive description of
svn status
and its output, see
svn status (stat, st).
4.7.2 Examine the details of your local modifications
Another way to examine your changes is with the svn diff
command, which displays differences in file content.
When you run svn diff
at the top of your working copy with no arguments, Subversion will print the changes you've made to human-readable files in your working copy.
It displays those changes in unified diff format, a format which describes changes as “hunks” (or “snippets”) of a file's content where each line of text is prefixed with a single-character code:
a space, which means the line was unchanged;
a minus sign (−), which means the line was removed from the file;
or a plus sign (+), which means the line was added to the file.
In the context of svn diff
, those minus-sign-prefixed and plus-sign-prefixed lines show how the lines looked before and after your modifications, respectively.
Here's an example:
$ svn diff
Index: bar.c
===================================================================
--- bar.c (revision 3)
+++ bar.c (working copy)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>
int main(void) {
- printf("Sixty-four slices of American Cheese...\n");
+ printf("Sixty-five slices of American Cheese...\n");
return 0;
}
Index: README
===================================================================
--- README (revision 3)
+++ README (working copy)
@@ -193,3 +193,4 @@
+Note to self: pick up laundry.
Index: stuff/fish.c
===================================================================
--- stuff/fish.c (revision 1)
+++ stuff/fish.c (working copy)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.
Index: stuff/things/bloo.h
===================================================================
--- stuff/things/bloo.h (revision 8)
+++ stuff/things/bloo.h (working copy)
+Here is a new file to describe
+things about bloo.
The svn diff
command produces this output by comparing your working files against its pristine text-base.
Files scheduled for addition are displayed as files in which every line was added.
Files scheduled for deletion are displayed as if every line was removed from those files.
The output from svn diff
is somehwat compatible with the patch
program—more so with the svn patch
command (introduced in Subversion 1.7).
Patch processing commands such as these read and apply patch files (or “patches”), which are files that describe differences made to one or more files.
Because of this, you can share the changes you've made in your working copy with someone else without first committing those changes by creating a patch file from the redirected output of svn diff
:
$ svn diff > patchfile
$
Subversion uses its internal diff engine, which produces unified diff format, by default. If you want diff output in a different format, specify an external diff program using --diff-cmd
and pass any additional flags that it needs via the --extensions
(-x
) option.
For example, you might want Subversion to defer its difference calculation and display to the GNU diff
program,
asking that program to print local modifications made to the file foo.c
in context diff format
(another flavor of difference format) while ignoring changes made only to
the case of the letters used in the file's contents:
$ svn diff --diff-cmd /usr/bin/diff -x "-i" foo.c
...
$