how to enable lfs in a codeup repository - Alibaba Cloud DevOps

This topic describes how to enable Large File Storage (LFS) for a Codeup repository to manage binary files more efficiently. It also provides solutions for migrating LFS files when you import a third-party repository to Codeup.

Scenarios

This topic covers the following scenarios. You can perform the operations that apply to your situation.

Enable LFS for a Codeup repository.
Enable LFS for a Codeup repository and migrate historical files to LFS.
Migrate a third-party repository to Codeup and enable LFS.
Migrate a third-party repository to Codeup, enable LFS, and migrate historical files to LFS.
Migrate a third-party repository that already has LFS enabled to Codeup.

Install and use LFS

For instructions, see How to use Git LFS?. After you complete the installation, run the following command:

$ git lfs -v

This command checks whether LFS is installed correctly and displays its version number.

Use LFS to manage binary files in Codeup

Enable LFS for a Codeup repository

If your repository has no historical commits with large files (binary files) to be managed by LFS, or if you are starting with an empty repository, the process is straightforward. The following steps describe how to enable and use LFS for a Codeup repository without modifying historical commits.

Back up the repository: Before you begin, back up your repository. Run the following command to create a backup in a local folder named `backup`:
```
$ git clone --bare gi*@codeup.aliyun.com:<organization or group ID>/<repository address> backup
```
Navigate to the local repository: After the backup is complete, navigate to an existing local repository or reclone one to use as your working directory. To track PNG image 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 and push the changes: Run the `add` and `commit` commands, and then push the changes to the remote repository.
```
$ git add .
$ git commit -m "Manage png files with LFS"
$ git push
```
The output contains text such as Uploading LFS objects done. This message indicates that LFS is enabled and the files have been uploaded.
Open the repository page. The `lfs.png` file is marked as managed by LFS.
On the Settings > Large File Storage page, you can also view information, such as the total size of LFS objects, file types, and committers. You can then reclone the repository by running the following command:
```
$ git clone gi*@codeup.aliyun.com:<organization or group ID>/<repository address>
```
The PNG file is automatically checked out. No extra operations are required.

Codeup repository: Enable LFS and migrate historical files

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

Back up the repository: First, back up your repository.
```
$ git clone --bare $ gi*@codeup.aliyun.com:<organization or group ID>/<repository address> backup
```
We recommend that you migrate one branch at a time.
Clone the repository and migrate branches: When you clone the repository, perform a bare clone to fetch all references from the remote repository. This prevents omissions that could cause the migration to fail for historical commits in some branches and references.
```
git clone --mirror <remote repository URL> <local folder name>
```
Navigate to the bare repository folder and run the following command:
```
$ 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.
```
The output shows that the historical commits are rewritten. This action migrates the historical PNG files on the master branch to be 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"
```
If you have other branches and references, repeat this step.
Push the migrated bare repository: Run the following command to push the migrated branches and tags to the remote repository:
```
$ git push --mirror --force
```
As a result, the historical PNG files are now managed by LFS. Any new PNG files that you add will also be managed by LFS.
If you have many branches, you can migrate all of them at once. Run the following command to migrate the historical PNG images on all local branches to be managed by LFS:
```
$ git lfs migrate import --everything --include="*.png"
```
Note
- Migrating all branches at once may cause issues, such as file upload timeouts. If this issue occurs, migrate each branch individually.
- If your repository was previously hosted on Codeup and has a merge request history, your bare repository contains special references that track the merge request history, such as `refs/changes/1`, `refs/changes/1/head`, and `refs/changes/1/target/1`. When you migrate, you must specify the `--everything` option to migrate these references as well.

Migrate a third-party repository to Codeup and enable LFS

To migrate a repository from another platform to Codeup and enable LFS, perform the following 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 a third-party repository to Codeup, enable LFS, and migrate historical files

If you want to migrate a repository from another platform to Codeup and migrate its historical files, perform the following steps:

Follow the first three steps in Codeup repository: Enable LFS and migrate historical files to migrate the historical commits on all local branches, but do not run the git push command yet.
Before you run the git push command, run the following command:
```
$ git remote add codeup <Codeup repository address>
```

Run the following commands:

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

Open the Codeup repository page to verify that the repository was successfully uploaded.

Migrate a third-party repository with LFS enabled to Codeup

If you have enabled LFS on another platform and want to migrate your repository to Codeup, perform the following steps:

First, perform a full clone of the repository:

$ git clone --bare <address of the other repository>

Then, download all LFS files to your local machine:
```
$ git lfs fetch --all origin
```
After the download is complete, change the remote address of the repository to the Codeup repository address:
```
$ git remote add codeup gi*@codeup.aliyun.com:<organization or group ID>/<repository name>
```
Then, push the LFS files to Codeup:
```
$ git lfs push --all codeup
```
After the push is complete, run the following commands:
```
$ git push --all codeup
$ git push --tags codeup
```
This completes the migration of an existing LFS-enabled repository to Codeup.

Important

If the LFS files that you are migrating are large, you may encounter issues such as a server connection timeout when you push the repository. For example, the `git push` command may finish pushing the LFS files but fail to update the remote repository references. If this issue occurs, you can perform the push operation in two steps:

First, run the git lfs push --all origin command to push the LFS files to the server.
Then, run the git push --all --no-verify command to skip the LFS file check and update the remote repository references.

For more detailed instructions on how to use LFS, see Introduction to the Codeup Git LFS feature.