- Day-by-day import
- Label-by-label import
- Resume imports
- Keyword expansion
- Pipe data to
git fast-importor dump to files
- Merge history is not imported
- Use git-starteam-merges to reconstruct history after import
Git-StarTeam use an ant script to build its jar file.
cd ~/proj/git-starteam/ ant -Djargs.jar=/path/to/jargs.jar -Dstarteam.jar=/path/to/starteam.jar jar
StarTeam SDK versions 8.0, 10.4 and 11.0 are known to work. Version 12.5 is not compatible.
A StarTeam project where a large number of files were checked in at one time might exceed maximum open file limits on your operating system.
On Linux, this can be changed with
ulimit -n 16384. If this fails, it may
help to add the line
* - nofile 65536 to
then logout and back in. The
* may be replaced with a specific username.
The default max "open files" is 16384 on Windows and likely won't need tuning.
Command Line Usage
The main Java class is
org.sync.MainEntry. The following jars must be in your Java classpath:
Running the command with no options will display usage information.
These options must be set for all runs:
-h <host>StarTeam server hostname
-P <port>StarTeam server port
-p <project>StarTeam project
-v <view>StarTeam view
There are four primary modes of operation:
- Import latest revisions
- Import label by label
- Import day by day
- Import all labels
All four modes can:
- Restrict the import to a specific folder using
git fast-importdata to files for debugging using
-D <dump file prefix>option.
- Log their operations to stderr with the
- Specify the path to the Git executable with the
-X <path to git>option.
- Specify the Git repository location with the
- Automatically create the Git repository (as a bare repo) with the
- Expand StarTeam keywords with the
- Select the StarTeam user and password with the
- Specify a file containing a mapping of user names to emails with
-m <mailMappingFile>. This mapping will be used in case the user performing the conversion does not have the required administrator access to extract email addresses from the StarTeam server.
- Specify the domain to append to StarTeam user names with
-d <domain>. This mapping will be used in case the user performing the conversion does not have the required administrator access to extract email addresses from the StarTeam server, and an explicit mapping cannot be found in the mail mapping file if one is provided with the
-m <mailMappingFile>command line option.
The first three modes can:
- Add new commits to an existing repository using
- Specify the Git branch name with the
-H <head>option. Uses the view name by default.
Latest Revisions Mode
Latest revisions mode is the default.
This mode imports the latest revision of each file accessible from the view.
Equivalent revisions will grouped into a single Git commit. Two revisions are considered equivalent when:
- The revisions were created by the same user.
- Either of the revisions has an empty comment or they have the same comment, ignoring case.
- No revision was created between them in time.
file1.c: user1 3:50pm Message 1 file2.c: user1 3:51pm <empty log message> file3.c: user2 3:52pm <empty log message> file4.c: user1 3:53pm <empty log message>
file1.c and file2.c will be grouped into a git commit, file3.c will be in another commit by itself, and file4.c will be in another commit by itself. If file3.c had not been checked in between file2.c and file4.c, then file1.c, file2.c, and file4.c would have all been grouped into a single commit.
-R option is used, all commits will be made on top of the
branch specified by the
-H <head> option.
-t option is not valid in latest revisions mode.
-L option enables label-by-label mode.
This mode imports the file revisions of each successive label. The file revisions will be grouped into commits as in latest revisions mode.
-R option is used, only labels created after the date of
the last commit on the branch specified by the
-H <head> option will
be imported. If the
-t <time> option is also used with
only labels created after the given time will be imported.
A lightweight Git tag will be created for each StarTeam label.
-T option enables day-by-day mode.
This mode imports the file revisions at the end (23:59:59) of each successive day. The file revisions will be grouped into commits as in latest revisions mode.
-R option is used, the first day imported will be the date
of the last commit on the branch specified by the
-H <head> option.
-t option can be used to specify the starting time directly.
-A option enables all-views mode.
All-views mode does a label-by-label import of every derived view from the
root view. The root view may be passed in with the
-v <view> option or
will be automatically found by traversing up the view tree from the default
project view if no
-v <view> option is given.
--skip-views <regex> option may be given to prevent specific views
from being imported. All of the views that will be imported and skipped will
be logged at the beginning of the import run so that you may kill the import
and make changes if the list is not what you intend.
All-views is intended for one-time import of old project history. After the
initial all-views import, one of the other modes may be used with the
option to keep the git branches in sync with StarTeam.
All-Views Mode Script
#!/bin/sh # kill existing run, cleanup it's temp files pkill -9 -U $LOGNAME -f org.sync.MainEntry sleep 1 rm -f /tmp/Star*.tmp REPO=/pub/gittrees/vlc2android.git rm -rf $REPO git init --bare $REPO ( setsid java \ -classpath $(echo *.jar | tr ' ' :) \ -Xms2000M \ -Xmx2000M \ org.sync.MainEntry \ -h 22.214.171.124 -P 49203 \ -p Prime -A --skip-views '^xToDelete' \ -d gmail.com \ -f Src/apps/vlc2android \ -U UserName \ -W $REPO \ --verbose & ) >vlc2android-all.log 2>&1 </dev/null
Add mapping of user names to actual email address
In case the user performing the conversion does not have StarTeam user account admin access, the emails can be specified using a mapping file as follow:
Create mapping file:
echo "John Smith = email@example.com" > mailmap echo "J. Random Hacker = firstname.lastname@example.org" >> mailmap ...
Execute importation with additional
-m <mailmap>command line option. If the
-d <domain>is also provided, users which are not found in
mailmapwill get an email using the default domain provided.
Latest Revisions Mode
bin/.git/folder from a StarTeam project named
cd ~/proj/git-starteam/bin/ java -cp jargs.jar:starteam110.jar:syncronizer.jar org.sync.MainEntry -h 126.96.36.199 -P 49203 -p Prime -v Prime -H master -U UserName -d gmail.com -f Src/apps/vlc2android/ -c
Or, it's a good idea to add
.gitignorefirst, so you can do below instead:
cd ~/proj/git-starteam/bin/ echo "*.o" > .gitignore git add .gitignore git commit -m "Init with .gitignore" java -cp jargs.jar:starteam110.jar:syncronizer.jar org.sync.MainEntry -h 188.8.131.52 -P 49203 -p Prime -v Prime -H master -U UserName -d gmail.com -f Src/apps/vlc2android/ -R
Add other branch to
bin/.git/folder from other view:
gitk --all, create
OtherViewbranch base on the commit which time is nearest before
StarTeam->View->Properties->Type->Parent Configurationof the Other View.
java -cp jargs.jar:starteam110.jar:syncronizer.jar org.sync.MainEntry -h 184.108.40.206 -P 49203 -p Prime -v OtherView -H other-view -U UserName -d gmail.com -f Src/apps/vlc2android -R
Get the repository:
cd /pub/gittrees/ git clone --bare ~/proj/git-starteam/bin/.git vlc2android.git
Delete bin/.git/ folder
cd ~/proj/git-starteam/bin/ rm -rf .git/
Build with Fake-StarTeam
Fake-StarTeam may be used to test Git-StarTeam itself. To build it, run ant as follows:
cd ~/proj/git-starteam/ ant -Djargs.jar=/path/to/jargs.jar -Dstarteam.jar=bin/fake-starteam.jar fake-starteam jar
Run Unit Tests
The unit tests currently assume they will be run from the syncronizer subdirectory and in the UTC-0500 timezone.
cd ~/proj/git-starteam/syncronizer TZ=America/Montreal ant -f ../build.xml -Dstarteam.bin=bin/fake-starteam clean fake-starteam test
- Push to StarTeam
Git-StarTeam is convered under the GNU General Public License Version 3.
Fake-StarTeam is convered under a personal license and is included only for testing purpose. The project shall not be used for any other purpose than easly testing your interaction with a fake StarTeam server.
git-st is a Git remote helper for StarTeam.