summaryrefslogtreecommitdiff
path: root/Documentation/git-svn.txt
diff options
context:
space:
mode:
authorJonathan Nieder <jrnieder@uchicago.edu>2008-06-30 18:56:34 (GMT)
committerJunio C Hamano <gitster@pobox.com>2008-07-02 00:20:16 (GMT)
commit483bc4f045881b998512ae814d6cf44d0c0cb493 (patch)
tree1812b25a8f08841bd4cfb6566636ce6fb5b8eac3 /Documentation/git-svn.txt
parentb1889c36d85514e5e70462294c561a02c2edfe2b (diff)
downloadgit-483bc4f045881b998512ae814d6cf44d0c0cb493.zip
git-483bc4f045881b998512ae814d6cf44d0c0cb493.tar.gz
git-483bc4f045881b998512ae814d6cf44d0c0cb493.tar.bz2
Documentation formatting and cleanup
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/git-svn.txt')
-rw-r--r--Documentation/git-svn.txt133
1 files changed, 66 insertions, 67 deletions
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 6ddfed3..6caa130 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -11,17 +11,17 @@ SYNOPSIS
DESCRIPTION
-----------
-git-svn is a simple conduit for changesets between Subversion and git.
+`git-svn` is a simple conduit for changesets between Subversion and git.
It is not to be confused with linkgit:git-svnimport[1], which is
read-only.
-git-svn was originally designed for an individual developer who wants a
+`git-svn` was originally designed for an individual developer who wants a
bidirectional flow of changesets between a single branch in Subversion
and an arbitrary number of branches in git. Since its inception,
-git-svn has gained the ability to track multiple branches in a manner
-similar to git-svnimport.
+`git-svn` has gained the ability to track multiple branches in a manner
+similar to `git-svnimport`.
-git-svn is especially useful when it comes to tracking repositories
+`git-svn` is especially useful when it comes to tracking repositories
not organized in the way Subversion developers recommend (trunk,
branches, tags directories).
@@ -31,7 +31,7 @@ COMMANDS
'init'::
Initializes an empty git repository with additional
- metadata directories for git-svn. The Subversion URL
+ metadata directories for `git-svn`. The Subversion URL
may be specified as a command-line argument, or as full
URL arguments to -T/-t/-b. Optionally, the target
directory to operate on can be specified as a second
@@ -107,20 +107,20 @@ COMMANDS
This fetches revisions from the SVN parent of the current HEAD
and rebases the current (uncommitted to SVN) work against it.
-This works similarly to 'svn update' or 'git-pull' except that
-it preserves linear history with 'git-rebase' instead of
-'git-merge' for ease of dcommiting with git-svn.
+This works similarly to `svn update` or `git-pull` except that
+it preserves linear history with `git-rebase` instead of
+`git-merge` for ease of dcommiting with `git-svn`.
-This accepts all options that 'git-svn fetch' and 'git-rebase'
-accepts. However '--fetch-all' only fetches from the current
+This accepts all options that `git-svn fetch` and `git-rebase`
+accept. However, '--fetch-all' only fetches from the current
[svn-remote], and not all [svn-remote] definitions.
-Like 'git-rebase'; this requires that the working tree be clean
+Like `git-rebase`; this requires that the working tree be clean
and have no uncommitted changes.
-l;;
--local;;
- Do not fetch remotely; only run 'git-rebase' against the
+ Do not fetch remotely; only run `git-rebase` against the
last fetched commit from the upstream SVN.
'dcommit'::
@@ -128,7 +128,7 @@ and have no uncommitted changes.
repository, and then rebase or reset (depending on whether or
not there is a diff between SVN and head). This will create
a revision in SVN for each commit in git.
- It is recommended that you run git-svn fetch and rebase (not
+ It is recommended that you run `git-svn` fetch and rebase (not
pull or merge) your commits against the latest changes in the
SVN repository.
An optional command-line argument may be specified as an
@@ -173,7 +173,7 @@ NOTE: SVN itself only stores times in UTC and nothing else. The regular svn
client converts the UTC time to the local time (or based on the TZ=
environment). This command has the same behaviour.
+
-Any other arguments are passed directly to `git-log'
+Any other arguments are passed directly to `git-log`
'blame'::
Show what revision and author last modified each line of a file. The
@@ -181,10 +181,10 @@ Any other arguments are passed directly to `git-log'
`svn blame' by default. Like the SVN blame command,
local uncommitted changes in the working copy are ignored;
the version of the file in the HEAD revision is annotated. Unknown
- arguments are passed directly to git-blame.
+ arguments are passed directly to `git-blame`.
+
--git-format;;
- Produce output in the same format as `git-blame', but with
+ Produce output in the same format as `git-blame`, but with
SVN revision numbers instead of git commit hashes. In this mode,
changes that haven't been committed to SVN (including local
working-copy edits) are shown as revision 0.
@@ -203,7 +203,7 @@ Any other arguments are passed directly to `git-log'
absolutely no attempts to do patching when committing to SVN, it
simply overwrites files with those specified in the tree or
commit. All merging is assumed to have taken place
- independently of git-svn functions.
+ independently of `git-svn` functions.
'create-ignore'::
Recursively finds the svn:ignore property on directories and
@@ -219,12 +219,12 @@ Any other arguments are passed directly to `git-log'
'commit-diff'::
Commits the diff of two tree-ish arguments from the
command-line. This command is intended for interoperability with
- git-svnimport and does not rely on being inside an git-svn
- init-ed repository. This command takes three arguments, (a) the
+ `git-svnimport` and does not rely on being inside an `git-svn
+ init`-ed repository. This command takes three arguments, (a) the
original tree to diff against, (b) the new tree result, (c) the
URL of the target Subversion repository. The final argument
- (URL) may be omitted if you are working from a git-svn-aware
- repository (that has been init-ed with git-svn).
+ (URL) may be omitted if you are working from a `git-svn`-aware
+ repository (that has been `init`-ed with `git-svn`).
The -r<revision> option is required for this.
'info'::
@@ -255,7 +255,7 @@ OPTIONS
--shared[={false|true|umask|group|all|world|everybody}]::
--template=<template_directory>::
Only used with the 'init' command.
- These are passed directly to linkgit:git-init[1].
+ These are passed directly to `git-init`.
-r <ARG>::
--revision <ARG>::
@@ -277,7 +277,7 @@ Only used with the 'set-tree' command.
Read a list of commits from stdin and commit them in reverse
order. Only the leading sha1 is read from each line, so
-git-rev-list --pretty=oneline output can be used.
+`git-rev-list --pretty=oneline` output can be used.
--rmdir::
@@ -307,7 +307,7 @@ config key: svn.edit
Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
-They are both passed directly to git-diff-tree see
+They are both passed directly to `git-diff-tree`; see
linkgit:git-diff-tree[1] for more information.
[verse]
@@ -317,24 +317,24 @@ config key: svn.findcopiesharder
-A<filename>::
--authors-file=<filename>::
-Syntax is compatible with the files used by git-svnimport and
-git-cvsimport:
+Syntax is compatible with the files used by `git-svnimport` and
+`git-cvsimport`:
------------------------------------------------------------------------
loginname = Joe User <user@example.com>
------------------------------------------------------------------------
-If this option is specified and git-svn encounters an SVN
-committer name that does not exist in the authors-file, git-svn
+If this option is specified and `git-svn` encounters an SVN
+committer name that does not exist in the authors-file, `git-svn`
will abort operation. The user will then have to add the
-appropriate entry. Re-running the previous git-svn command
+appropriate entry. Re-running the previous `git-svn` command
after the authors-file is modified should continue operation.
config key: svn.authorsfile
-q::
--quiet::
- Make git-svn less verbose.
+ Make `git-svn` less verbose.
--repack[=<n>]::
--repack-flags=<flags>::
@@ -346,7 +346,7 @@ with many revisions.
to fetch before repacking. This defaults to repacking every
1000 commits fetched if no argument is specified.
---repack-flags are passed directly to linkgit:git-repack[1].
+--repack-flags are passed directly to `git-repack`.
[verse]
config key: svn.repack
@@ -359,8 +359,8 @@ config key: svn.repackflags
These are only used with the 'dcommit' and 'rebase' commands.
-Passed directly to git-rebase when using 'dcommit' if a
-'git-reset' cannot be used (see dcommit).
+Passed directly to `git-rebase` when using 'dcommit' if a
+`git-reset` cannot be used (see 'dcommit').
-n::
--dry-run::
@@ -411,20 +411,20 @@ CONFIG FILE-ONLY OPTIONS
svn.noMetadata::
svn-remote.<name>.noMetadata::
-This gets rid of the git-svn-id: lines at the end of every commit.
+This gets rid of the 'git-svn-id:' lines at the end of every commit.
-If you lose your .git/svn/git-svn/.rev_db file, git-svn will not
+If you lose your .git/svn/git-svn/.rev_db file, `git-svn` will not
be able to rebuild it and you won't be able to fetch again,
either. This is fine for one-shot imports.
-The 'git-svn log' command will not work on repositories using
+The `git-svn log` command will not work on repositories using
this, either. Using this conflicts with the 'useSvmProps'
option for (hopefully) obvious reasons.
svn.useSvmProps::
svn-remote.<name>.useSvmProps::
-This allows git-svn to re-map repository URLs and UUIDs from
+This allows `git-svn` to re-map repository URLs and UUIDs from
mirrors created using SVN::Mirror (or svk) for metadata.
If an SVN revision has a property, "svm:headrev", it is likely
@@ -443,7 +443,7 @@ svn-remote.<name>.useSvnsyncprops::
svn-remote.<name>.rewriteRoot::
This allows users to create repositories from alternate
- URLs. For example, an administrator could run git-svn on the
+ URLs. For example, an administrator could run `git-svn` on the
server locally (accessing via file://) but wish to distribute
the repository with a public http:// or svn:// URL in the
metadata so users of it will see the public URL.
@@ -451,7 +451,7 @@ svn-remote.<name>.rewriteRoot::
--
Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
-options all affect the metadata generated and used by git-svn; they
+options all affect the metadata generated and used by `git-svn`; they
*must* be set in the configuration file before any history is imported
and these settings should never be changed once they are set.
@@ -498,12 +498,12 @@ Tracking and contributing to an entire Subversion-managed project
# of dcommit/rebase/show-ignore should be the same as above.
------------------------------------------------------------------------
-The initial 'git-svn clone' can be quite time-consuming
+The initial `git-svn clone` can be quite time-consuming
(especially for large Subversion repositories). If multiple
people (or one person with multiple machines) want to use
-git-svn to interact with the same Subversion repository, you can
-do the initial 'git-svn clone' to a repository on a server and
-have each person clone that repository with 'git-clone':
+`git-svn` to interact with the same Subversion repository, you can
+do the initial `git-svn clone` to a repository on a server and
+have each person clone that repository with `git-clone`:
------------------------------------------------------------------------
# Do the initial import on a server
@@ -524,22 +524,22 @@ have each person clone that repository with 'git-clone':
REBASE VS. PULL/MERGE
---------------------
-Originally, git-svn recommended that the remotes/git-svn branch be
+Originally, `git-svn` recommended that the 'remotes/git-svn' branch be
pulled or merged from. This is because the author favored
-'git svn set-tree B' to commit a single head rather than the
-'git svn set-tree A..B' notation to commit multiple commits.
+`git svn set-tree B` to commit a single head rather than the
+`git svn set-tree A..B` notation to commit multiple commits.
-If you use 'git svn set-tree A..B' to commit several diffs and you do
+If you use `git svn set-tree A..B` to commit several diffs and you do
not have the latest remotes/git-svn merged into my-branch, you should
-use 'git svn rebase' to update your work branch instead of 'git pull' or
-'git merge'. 'pull/merge' can cause non-linear history to be flattened
+use `git svn rebase` to update your work branch instead of `git pull` or
+`git merge`. `pull`/`merge' can cause non-linear history to be flattened
when committing into SVN, which can lead to merge commits reversing
previous commits in SVN.
DESIGN PHILOSOPHY
-----------------
Merge tracking in Subversion is lacking and doing branched development
-with Subversion can be cumbersome as a result. While git-svn can track
+with Subversion can be cumbersome as a result. While `git-svn` can track
copy history (including branches and tags) for repositories adopting a
standard layout, it cannot yet represent merge history that happened
inside git back upstream to SVN users. Therefore it is advised that
@@ -550,30 +550,30 @@ CAVEATS
-------
For the sake of simplicity and interoperating with a less-capable system
-(SVN), it is recommended that all git-svn users clone, fetch and dcommit
-directly from the SVN server, and avoid all git-clone/pull/merge/push
+(SVN), it is recommended that all `git-svn` users clone, fetch and dcommit
+directly from the SVN server, and avoid all `git-clone`/`pull`/`merge`/`push`
operations between git repositories and branches. The recommended
method of exchanging code between git branches and users is
-git-format-patch and git-am, or just dcommiting to the SVN repository.
+`git-format-patch` and `git-am`, or just 'dcommit'ing to the SVN repository.
-Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
-plan to dcommit from. Subversion does not represent merges in any
+Running `git-merge` or `git-pull` is NOT recommended on a branch you
+plan to 'dcommit' from. Subversion does not represent merges in any
reasonable or useful fashion; so users using Subversion cannot see any
merges you've made. Furthermore, if you merge or pull from a git branch
-that is a mirror of an SVN branch, dcommit may commit to the wrong
+that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
branch.
-'git-clone' does not clone branches under the refs/remotes/ hierarchy or
-any git-svn metadata, or config. So repositories created and managed with
-using git-svn should use rsync(1) for cloning, if cloning is to be done
+`git-clone` does not clone branches under the refs/remotes/ hierarchy or
+any `git-svn` metadata, or config. So repositories created and managed with
+using `git-svn` should use `rsync` for cloning, if cloning is to be done
at all.
-Since 'dcommit' uses rebase internally, any git branches you git-push to
-before dcommit on will require forcing an overwrite of the existing ref
+Since 'dcommit' uses rebase internally, any git branches you `git-push` to
+before 'dcommit' on will require forcing an overwrite of the existing ref
on the remote repository. This is generally considered bad practice,
-see the git-push(1) documentation for details.
+see the linkgit:git-push[1] documentation for details.
-Do not use the --amend option of git-commit(1) on a change you've
+Do not use the --amend option of linkgit:git-commit[1] on a change you've
already dcommitted. It is considered bad practice to --amend commits
you've already pushed to a remote repository for other users, and
dcommit with SVN is analogous to that.
@@ -594,7 +594,7 @@ for git to detect them.
CONFIGURATION
-------------
-git-svn stores [svn-remote] configuration information in the
+`git-svn` stores [svn-remote] configuration information in the
repository .git/config file. It is similar the core git
[remote] sections except 'fetch' keys do not accept glob
arguments; but they are instead handled by the 'branches'
@@ -615,8 +615,7 @@ Keep in mind that the '*' (asterisk) wildcard of the local ref
however the remote wildcard may be anywhere as long as it's own
independent path component (surrounded by '/' or EOL). This
type of configuration is not automatically created by 'init' and
-should be manually entered with a text-editor or using
-linkgit:git-config[1]
+should be manually entered with a text-editor or using `git-config`.
SEE ALSO
--------