how to enable LFS in a Codeup repository-Alibaba Cloud DevOps(Alibaba Cloud DevOps)-阿里云帮助中心

This guide explains how to enable Git Large File Storage (LFS) in your Codeup repository to manage binary files more efficiently and provides solutions for migrating LFS files when you move a third-party repository to Codeup.

Use cases

This guide covers the following scenarios. Choose the one that applies to you.

Enable LFS for a Codeup repository.
Enable LFS and migrate files from historical commits to LFS in a Codeup repository.
Migrate a third-party repository to Codeup and enable LFS.
Migrate a third-party repository to Codeup, enable LFS, and convert its historical files.
Migrate a third-party repository that already uses LFS to Codeup.

For more information about installing and using LFS, see Git Large File Storage.

Install and use LFS

For more information, see How to use Git LFS?. After the installation is complete, you can run the following:

$ git lfs -v

This command verifies your LFS installation and displays the version.

Using LFS in Codeup

Enable LFS

If your repository history contains no large files to track with LFS, or if you are starting with an empty repository, the process is simple. Follow these steps to enable and use LFS in a Codeup repository without rewriting commit history.

Back up the repository: Before you begin, we strongly recommend backing up your repository.

$ git clone --bare gi*@codeup.aliyun.com:<organization-or-group-id>/<repository-path> backup

Go to your local repository: After the backup completes, navigate to your existing local repository, or clone it again to create a new working directory. To track PNG files with LFS, run the following command:
```
$ git lfs track "*.png"
Tracking "*.png"
```
Then, add a PNG file to the repository. For example:
```
$ echo test > test.png
```
Commit the changes: Add, commit, and push your changes to the remote repository.
```
$ git add .
$ git commit -m "Track PNG files with LFS"
$ git push
```
The output includes a line similar to Uploading LFS objects... done, which confirms that LFS is enabled and the files have been uploaded.

On the repository page, you can see that test.png is now marked as managed by LFS.

In the repository, navigate to . On this page, you can view information such as the total size of LFS objects, file types, and committers. Now, clone the repository again:
```
$ git clone gi*@codeup.aliyun.com:<organization-or-group-id>/<repository-path>
```
You can see that the PNG file is automatically checked out with no extra steps required.

Migrate history

In many cases, large files have already been committed to a repository. Enabling LFS affects only future commits; it does not convert existing files. You can use the git lfs migrate command to migrate these historical files.

Back up the repository: First, we strongly recommend backing up the repository:
```
$ git clone --bare gi*@codeup.aliyun.com:<organization-or-group-id>/<repository-path> backup
```
We recommend that you migrate one branch at a time.
Clone the repository and migrate a branch: To ensure all references are fetched and no historical commits are missed, clone a mirror of the repository.
```
git clone --mirror <remote-repository-url> <local-directory-name>
```
Navigate to the bare repository directory and run the following command to migrate the master branch:
```
$ git lfs migrate import --include-ref=master --include="*.png"
```
The output is similar to the following:
```
migrate: Sorting commits: ..., done.
migrate: Rewriting commits: 100% (2/2), done.
  master 2d2c813aac4b2247e4b79b3721cca45580f15282 -> 5634c182663a24617bd26d0d82a3966686687173
migrate: Updating refs: ..., done.
migrate: checkout: ..., done.
```
This confirms that the commit history has been rewritten and the historical PNG files on the master branch are now managed by LFS.
Migrate other branches and references: For example, to migrate the dev branch, run the following command:
```
$ git lfs migrate import --include-ref=dev --include="*.png"
```
Repeat this process for any other branches and references you need to migrate.
Push the migrated bare repository: Run the following command to push all updated branches and tags to the remote repository:
```
$ git push --mirror --force
```
This migrates the historical PNG files to LFS. New PNG files will also be tracked by LFS.
If your repository has many branches, you can migrate them all at once. Run the following command to convert all historical PNG files across all local branches to LFS:
```
$ git lfs migrate import --everything --include="*.png"
```
Note
- Migrating all branches at once can cause issues such as upload timeouts. If you encounter timeouts, migrate one branch at a time.
- If your repository was previously hosted on Codeup and has a merge request history, your bare repository contains special references for this history, such as refs/changes/1, refs/changes/1/head, and refs/changes/1/target/1. You must use the --everything flag to ensure these references are also migrated.

Migrate a third-party repository

If you want to migrate a repository from another platform to Codeup and enable LFS, follow these steps:

Import the repository from the other platform to Codeup.
After the import is complete, follow the instructions in Enable LFS for a Codeup repository to enable LFS.

Migrate repository and history

Follow these steps if you are migrating a repository from another platform to Codeup and want to convert its historical files to LFS.

Follow the first three steps in the Enable LFS and migrate historical files in a Codeup repository section to migrate the historical commits for all local branches. Do not run the git push command yet.
Before you run the git push command, run the following:
```
$ git remote add codeup <Codeup-repository-url>
```

Push all branches and tags to the new remote:

git push --all --force codeup
git push --tags --force codeup

Open the repository page in Codeup to confirm that the repository has been successfully uploaded.

Migrate an LFS-enabled repository

If you want to migrate a repository that already uses LFS on another platform to Codeup, follow these steps:

First, create a bare clone of the original repository:
```
$ git clone --bare <third-party-repository-url>
```
Next, download all LFS objects:
```
$ git lfs fetch --all origin
```

After the download completes, add your Codeup repository as a new remote named codeup:

$ git remote add codeup gi*@codeup.aliyun.com:<organization-or-group-id>/<repository-name>

Then, push the LFS objects to the new Codeup remote:
```
$ git lfs push --all codeup
```
Finally, push all branches and tags to the Codeup remote:
```
$ git push --all codeup
$ git push --tags codeup
```
This completes the migration of a repository with existing LFS objects to Codeup.

Important

If you are migrating a large number of LFS objects, the push operation may time out. A common symptom is that the git push command finishes immediately after pushing the LFS objects but does not update the remote references. If this happens, split the push into two steps:

First, push only the LFS objects to the server with the git lfs push --all codeup command.
Then, update the remote references with the git push --all --no-verify codeup command. This skips pushing or verifying the LFS objects again.

For more detailed information about using LFS, see Introduction to the Git LFS feature of Codeup.