title:Source Import API enhancements for working with Git LFS

author_name:lizzhale

Today we're introducing enhancements to the[Source Import API][docs] to support importing repositories with files larger than 100MB.

**Changes to parameters for starting an import**

[Starting an import][start-an-import] no longer requires a`vcs` parameter. Please be aware that without this parameter, the import job will take additional time to detect the vcs type before beginning the import. This detection step will be reflected in the response.

**New methods**

We've added 3 new methods that will enable API consumers to:

*[update][update-existing-import] the authentication or project choice for an import. If no parameters are provided during the request, the import will be restarted. Please note that this is a**breaking change**. Updating authentication for the originating URL is no longer supported through the[start an import][start-an-import] method. Please update your applications to use the new method.

*[set their preference][set-git-lfs-preference] for using Git LFS to import files larger than 100MB.

*[list all the files larger than 100MB][get-large-files] that were found during the import.

**New attributes for Git LFS**

Several new response attributes (`use_lfs`,`has_large_files`,`large_files_size`,`large_files`) were added to provide details regarding the large files found during the import. You can read more about the attributes[here][git-lfs-related-fields].

As before, to access the API during the preview period, you must provide a custom[media type][media-type] in the`Accept` header:

For more information, see the[Source Import API documentation][docs], and if you have any questions or feedback, please[let us know][contact].

[docs]:/v3/migration/source_imports/

[start-an-import]:/v3/migration/source_imports/#start-an-import

[update-existing-import]:/v3/migration/source_imports/#update-existing-import

[set-git-lfs-preference]:/v3/migration/source_imports/#set-git-lfs-preference

[get-large-files]:/v3/migration/source_imports/#get-large-files

[git-lfs-related-fields]:/v3/migration/source_imports/#git-lfs-related-fields

[media-type]:/v3/media

[contact]:https://github.com/contact?form%5Bsubject%5D=Source+Import+API

The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as[the GitHub Importer](https://import.github.com/).

A typical source import would[start the import](#start-an-import) and then (optionally)[update the authors](#map-a-commit-author). A more detailed example can be seen in this diagram:

A typical source import would[start the import](#start-an-import) and then (optionally)[update the authors](#map-a-commit-author) and/or[set the preference](#set-git-lfs-preference) for using Git LFS if large files exist in the import. A more detailed example can be seen in this diagram:

Name | Type | Description

-----|------|--------------

`vcs`|`string`|**Required** The originating VCS type. Can be one of "subversion", "git", "mercurial", or "tfvc".

`vcs_url`|`url`|**Required** The URL of the originating repository.

`vcs`|`string`|The originating VCS type. Can be one of`subversion`,`git`,`mercurial`, or`tfvc`. Please be aware that without this parameter, the import job will take additional time to detect the VCS type before beginning the import. This detection step will be reflected in the response.

`vcs_username`|`string`|If authentication is required, the username to provide to`vcs_url`.

`vcs_password`|`string`|If authentication is required, the password to provide to`vcs_url`.

`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported.

View the progress of an import.

<%= headers 200 %>

An import that does not have errors will progress through these steps:

*`detecting` - the "detection" step of the import is in progress because the request did not include a`vcs` parameter. The import is identifying the type of source control present at the URL.

*`importing` - the "raw" step of the import is in progress. This is where commit data is fetched from the original repository. The import progress response will include`commit_count` (the total number of raw commits that will be imported) and`percent` (0 - 100, the current progress through the import).

*`mapping` - the "rewrite" step of the import is in progress. This is where SVN branches are converted to Git branches, and where author updates are applied. The import progress response does not include progress information.

*`pushing` - the "push" step of the import is in progress. This is where the importer updates the repository on GitHub. The import progress response will include`push_percent`, which is the percent value reported by`git push` when it is "Writing objects".

*`complete` - the import is complete, and the repository is ready on GitHub.

If there are problems, you will see one of these in the`status` field:

*`auth_failed` - the import requires authentication in order to connect to the original repository. Makeanother "Start Import" request, and include`vcs_username` and`vcs_password`.

*`auth_failed` - the import requires authentication in order to connect to the original repository. Makean "Update Existing Import" request, and include`vcs_username` and`vcs_password`.

*`error` - the import encountered an error. The import progress response will include the`failed_step` and an error message.[Contact support](https://github.com/contact?form%5Bsubject%5D=Source+Import+API+error) for more information.

*`detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. Make an "Update Existing Import" request, and include`vcs_username` and`vcs_password`.

*`detection_found_nothing` - the importer didn't recognize any source control at the URL.

*`detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a`project_choices` field with the possible project choices as values. Make an "Update Existing Import" request, and include`vcs` and (if applicable)`tfvc_project`.

This section includes details about Git LFS related fields that may be present in the Import Progress response.

*`use_lfs` - describes whether the import has been opted in or out of using Git LFS. The value can be`opt_in`,`opt_out`, or`undecided` if no action has been taken.

*`has_large_files` - the boolean value describing whether files larger than 100MB were found during the`importing` step.

*`large_files_size` - the total size in gigabytes of files larger than 100MB found in the originating repository.

*`large_files_count` - the total number of of files larger than 100MB found in the originating repository. To see a list of these files, make a "Get Large Files" request.

An import can be updated with credentials or a`project_choice` by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted.

<%= headers 200,:Location => "https://api.github.com/repos/spraints/socm/import" %>

<%= json:source_import %>

Name | Type | Description

-----|------|--------------

`vcs_username`|`string`|The username to provide to the originating repository.

`vcs_password`|`string`|The password to provide to the originating repository.

<%= json\

:vcs_username => "octocat",

:vcs_password => "secret"

%>

<%= headers 200 %>

<%= json:source_import_update_auth %>

If you query import statusforan import started via the web UI, you may also see these states:

*`detecting` - you've entered a URL via the web UI, and the importer is figuring out what type of source control is present at the URL.

*`detection_needs_auth` - you've entered a URL via the web UI, and the importer needs you to enter authentication credentials in the web UI in order to continue detection.

*`detection_found_nothing` - the importer didn't recognize any source control at the URL entered via the web UI.

*`detection_found_multiple` - the importer found several projects or repositories at the provided URL.

*`waiting_to_push` - the raw and rewrite steps are complete, but a destination GitHub repository hasn't been created yet.

Name | Type | Description

-----|------|--------------

`vcs`|`string`|The chosen project's VCS type.

`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported.

<%= json\

:vcs => "tfvc",

:tfvc_project => "project"

%>

<%= headers 200 %>

<%= json:source_import_update_project_choice %>

This API method and the "Map a commit author" method allow you to provide correct Git author information.

Name | Type | Description

Update an author's identity for the import. Your application can continue updating authors any time before you push new commits to the repository.

Name | Type | Description

<%= headers 200 %>

<%= json:source_import_author %>

You can import repositories from Subversion, Mercurial, and TFS that include files larger than 100MB. This ability is powered by[Git LFS](https://git-lfs.github.com). You can learn more about our LFS feature and working with large files[on our help site](https://help.github.com/articles/versioning-large-files/).

Name | Type | Description

-----|------|--------------

`use_lfs`|`string`|**Required** Can be one of`opt_in` (large files will be stored using Git LFS) or`opt_out` (large files will be removed during the import).

<%= json\

:use_lfs => "opt_in"

%>

<%= headers 200 %>

<%= json:source_import_complete %>

List files larger than 100MB found during the import

<%= headers 200 %>

<%= json:source_import_large_files %>

Stop an import for a repository.

SOURCE_IMPORT ||={

SOURCE_IMPORT_COMPLETE ||={

SOURCE_IMPORT_UPDATE_AUTH ||={

"vcs":"subversion",

"use_lfs":"undecided",

"vcs_url":"http://svn.mycompany.com/svn/myproject",

"status":"detecting",

SOURCE_IMPORT_UPDATE_PROJECT_CHOICE ||={

"use_lfs":"undecided",

"tfvc_project":"project",

SOURCE_IMPORT_AUTHOR ||={

SOURCE_IMPORT_LARGE_FILES ||=[

"ref_name":"refs/heads/master",

"path":"foo/bar/1",

"oid":"d3d9446802a44259755d38e6d163e820",

"size":10485760

"ref_name":"refs/heads/master",

"path":"foo/bar/2",

"oid":"6512bd43d9caa6e02c990b0a82652dca",

"size":11534336

"ref_name":"refs/heads/master",

"path":"foo/bar/3",

"oid":"c20ad4d76fe97759aa27a0c99bff6710",

"size":12582912