Creating your first project

Basics

• Name: Give your project a name and type it in.
• ID: Project ID is created automatically based on the specified project name.

Version Control

• Project is hosted in multiple repositories: Select this option if your project is divided into a few separate repositories but building this project requires fetching all the repositories into specific locations under the root directory. Mapping multiple repositories allows you to watch and review changes in all of them from a single Upsource project.

  Click Add repository and specify the following settings for each repository:

  • Mount path: Specify a directory inside your project where this VCS root will reside.
  • Mapping ID: A unique ID of the VCS repository. It's generated automatically, but you can specify your own.
• Repository URL: The following formats are expected in the Repository URL (Server name) field for different version control systems:
  • Git: https://git.example.com/project or git://git.example.com/project

  • Subversion: http://svn.example.com/project/project>

    Branches: you can define one or more SVN paths where Upsource should be looking for SVN branches. Use rules like +: or -: to include or exclude branches. Branch paths are relative to the repository URL specified above. Pattern may contain one * to match any number of characters in directory name.

    Example for a standard SVN layout:

    +:trunk +:branches/*

• Mercurial: http://hg.example.com/project

• Perforce: perforce.example.com:1111

  Important:In order for Upsource to recognise a Perforce repository, you need to:

  1. Download and install _P4:COMMAND LINE_ on the machine with your Upsource installation.
  2. For Mac OS and Linux, specify PATH to _P4:COMMAND LINE_ in your system environment variables (see P4 instructions).
  3. Restart Upsource

  Workspace mapping

  To include the entire project, specify: //<depot>/<project>/...

  To include only selected directories of the project, list these directories followed by corresponding directories in Upsource (divided by a space). Example:

  //depot/project1/directory1/... //upsource/depot/project1/directory1/... //depot/project1/directory2/... //upsource/depot/project1/directory2/...
• Login, Password: Specify credentials to connect to your VCS.
• Check interval: Reflects how often Upsource checks for new revisions in the repository (every 300 seconds by default.)

If commits to your repository aren't usually made this frequently, consider setting _Check interval_ to a larger value.

See also: What is supported for each VCS

Upsource Properties

Build system defines whether Upsource is able to execute static code analysis in your repository and provide related features including displaying code issues, "Find usages", "Go to Declaration" etc.

This setting should only be considered if you are working on a project that uses Java, PHP, JavaScript, or Kotlin, as code analysis is only supported for these languages at this point. If you are working on a project that doesn't use these languages, you're safe to set Build system to None.

There's a separate option for projects that use Maven irrelevant of which IDE is used to maintain code, and also an option that enables code analysis when IntelliJ IDEA is used in the project irrelevant of build system (for example, if your project is built with Ant but you're using IntelliJ IDEA based IDE, then IntelliJ IDEA would be your choice of build system.)

• Choose IntelliJ IDEA:

  • If IDEA based IDE is used to maintain code regardless of the build system, and if the project's .idea folder is commited into your repository.

    If your team developers configure their IDE so each has different .idea folder, it's still recommended to store most of the .idea folder contents in version control, only omitting the user-specific settings, such as .idea/workspace.xml and .idea/shelf. Otherwise Upsource will not be able to provide code insight for your project.

  • For any PHP/JavaScript projects
• If Maven is selected as build system:
  • Path to project model should contain the path to the parent _pom.xml_ file (relative to project root). If your project modules are hosted in multiple repositories (e.g. each module in their own repository), you can configure them all in one Upsource project, and keep the parent pom.xml in the first repo.

  • Maven settings - if your project requires non-standard Maven settings, paste the content of your maven-settings.xml here (up to 20KB).

• If Gradle is selected as build system, Path to project model should contain the path to the build.gradle file (relative to project root). Please note: Android Studio projects are not currently supported.

  If you're planning to work on Gradle projects without a wrapper:

  1. In the <upsource_home>/conf directory, create a file upsource.user.properties
  2. Add the following line to that file: gradle.home.directory=<gradle_home>. Use double backslashes in the specified path (e.g. C:\\Users\\Jet\\Gradle)
  3. Restart Upsource
• Default branch - optionally specify the branch which you want to set as default. Setting the default branch will improve displaying the commits graph, rendering README files, comparing branches, etc.

External links

Upsource can detect references and turn them into hyperlinks. For example, issue references mentioned in commit messages or discussion comments (such as Fix PRJ-123) can be recognized by Upsource and linked to the corresponding issues in your tracker.

Click Add link and specify your tracker's URL and an issue ID pattern.

Issue Tracker Integration

Integration with known issue tracker enables additional features such as creating issues from code reviews and discussions.

Currently Upsource can integrate with YouTrack and Jira.

Please refer to Issue tracker integration for detailed instructions.

Finish

When you are done filling in the form, click Create Project (or Save changes if you're editing)

You'll be redirected to the Administration view (http://your-host-name:port_for_upsource/administration) that shows status summary for the project.

Meanwhile Upsource will start loading commit information from the repository, then fetching and indexing repository content.

All this could take a while for larger projects (up to several hours.) To track indexing progress, hover over the project name. You will most probably not be able to work with the project before these steps complete.

Upon completing them, Upsource will allow browsing code in revisions, displaying diffs in revisions, create and process code reviews etc.