Help Center/ CodeArts Repo/ User Guide/ Managing Code Files/ Managing Tags
Updated on 2024-11-22 GMT+08:00
View PDF
Share

Managing Tags

Git provides tags to help your team manage versions. You can use Git tags to mark commits to manage important versions in a project and search for historical versions.

A tag points to a commit like a reference. No matter how later versions change, the tag always points to the commit. It can be regarded as a version snapshot that is permanently saved (the version is removed from the repository only when being manually deleted).

When using Git to manage code, you can search for and trace historical versions based on commit IDs. A commit ID is a long string (as shown in the following figure) that is difficult to remember and not identifiable, compared with version numbers such as V 1.0.0. Therefore, you can tag and name important versions to easily remember and trace them. For example, tag a version as myTag_V1.0.0 or FirstCommercialVersion.

Creating a Tag for the Latest Commit on the Console

  1. Access the repository list.
  2. Click a repository to go to the details page.
  3. Click the Code and Tags tabs. The tag list is displayed.
  4. Click Create. In the following dialog box that is displayed, select a branch or tag.

    The tag name must meet the following requirements:

    • The name cannot start with a hyphen (-), period (.), refs/heads/, refs/remotes/, or slash (/).
    • Spaces and special characters such as [\<~^:?*!()'"|$&; are not supported.
    • The name cannot end with a period (.), slash (/), or .lock.
    • Two consecutive periods (..) are not allowed.
    • The name cannot contain this sequence @{.

    An annotated tag is generated if you enter a message (the content after -m). A lightweight tag is generated if you do not enter a message. (What are annotated tags?)

    The name cannot be the same as another branch or tag name.

  5. Click OK. A tag is generated based on the latest version of the branch. The tag list is displayed.

Creating a Tag for a Historical Version on the Console

  1. Access the repository list.
  2. Click a repository to go to the details page. On the Code tab page, click the Files and History tabs.
  3. In the historical commit list, click next to a commit record and select Create Tag. The dialog box for creating a tag for the historical version is displayed.

    An annotated tag is generated if you enter a message (the content after -m). A lightweight tag is generated if you do not enter a message. (What are annotated tags?)

  4. Click OK. A tag is generated based on the specified historical version of the branch. The tag list is displayed.

Managing Tags on the Console

  • All tags in the remote repository are displayed in the tag list. You can perform the following operations:
    • Click a tag in the Tag Name column to go to the file list of the tagged version.
    • Click a commit ID to go to the commit details page.
    • Click to download the file package of the labeled version in tar.gz or zip format.
    • Click to delete a tag from CodeArts Repo. (To delete the tag from the local repository, perform the clone, pull, or -d operation.)

    If an IP address whitelist is set for the repository, only hosts with whitelisted IP addresses can download the repository source code on the page. If no IP address whitelist is set for the repository, all hosts can download the repository source code.

  • You can create a branch based on a tag.
  • On the console, click the Files tab and click the file name of the target file. Click the Comparison tab to compare commit records of the file.

Tag Classification

Git provides two types of tags:

  • Lightweight tag: is only a reference pointing to a specific commit. It can be considered as an alias for the commit. 
    git tag <tag_name>

    The following figure shows the information of a lightweight tag. You can find that it is an alias of a commit.

  • Annotated tag: points to a specific commit, but is stored as a complete object in Git. Compared with lightweight tags, annotated tags contain messages (similar to code comments). In addition to the tag name and message, the tag information includes the name and email address of the person who creates the tag, and tag creation time/date. 
    git tag -a  <tag_name> -m "<message>"

    The following figure shows the information of an annotated tag, which points to a commit and contains more information than that of a lightweight tag.

Both types of tags can identify versions. Annotated tags contain more information and are stored in a more stable and secure structure in Git. They are more widely used in large enterprises and projects.

Common Git Commands for Tags

  • Creating a lightweight tag 
    git tag <tag_name>       # Add a lightweight tag to the latest commit.

    Example:

    git tag myTag1                   # Add a lightweight tag myTag1 to the latest commit.
  • Creating an annotated tag 
    git tag -a  <tag_name> -m "<message>"          # Add an annotated tag to the latest commit.

    Example:

    git tag -a myTag2 -m "This is a tag." # Add an annotated tag myTag2 to the latest commit, and the message is "This is a tag.".
  • Tagging a historical version
    You can also tag a historical version by running the git log command to obtain the commit ID of the historical version. The following uses an annotated tag as an example: 
    git log                 # The historical commit information is displayed. Obtain the commit ID (only the first several digits are required), as shown in the following figure. Press q to return.

    git tag -a historyTag -m "Tag a historical version." 6a5b7c8db    # Add tag historyTag to the historical version whose commit ID starts with 6a5b7c8d, and the message is "Tag a historical version.".
    • If no command output is displayed, the tag is successfully created. If the command output is displayed, indicating that the tag name already exists (as shown in the following figure), change the tag name and perform the operation again.

    • One commit can have multiple tags with unique names, as shown in the following figure.

  • Viewing tags in the local repository
    You can list all tag names in the current repository and add parameters to filter tags when using them. 
    git tag
  • Viewing details about a specified tag 
    git show <name_of_the_desired_tag>

    Example:

    Display the details about myTag1 and the commit information. The following shows an example command output:

    git show myTag1

  • Pushing a local tag to the remote repository
    • By default, tags are not pushed when you push files from the local repository to the remote one. Tags are automatically synchronized when you synchronize (clone or pull) content from the remote repository to the local one. Therefore, if you want to share local tags with others in the project, you need to run the following Git command separately. 
      git push <remote_repository_address_or_alias> <name_of_the_tag_to_be_pushed>      # Push the specified tag to the remote repository.

      Example:

      Push the local tag myTag1 to the remote repository whose alias is origin.

      git push origin myTag1
    • Run the following command to push all new local tags to the remote repository: 
      git push  <remote_repository_address_or_alias> --tags

      If you create a tag in the remote repository and a tag with the same name in the local repository, the tag will fail to be pushed due to the conflict. In this case, you need to delete one of the tags and push another tag again.

  • Deleting a local tag 
    git tag -d <name_of_the_tag_to_be_deleted>

    The following shows an example of deleting the local tag tag1.

  • Deleting a tag from the remote repository

    Similar to tag creation, tag deletion also needs to be manually pushed.

    git push <remote_repository_address_or_alias> :refs/tags/<name_of_the_tag_to_be_deleted>

    The following shows an example of deleting a tag.

    git push HTTPSOrigin :refs/tags/666               # Delete the tag 666 from the remote repository whose alias is HTTPSOrigin.

Obtaining a Historical Version Using Tags

If you want to view the code in a tagged version, you can check it out to the working directory. The code can be edited but cannot be added or committed because the checked-out version belongs only to a tag instead of a branch. You can create a branch based on the working directory, modify the code on the branch, and merge the branch into the master branch. The detailed steps are as follows:

  1. Check out a historical version using a tag. 
    git checkout V2.0.0                  # Check out the version tagged with V2.0.0 to the working directory.

  2. Create a branch based on the current working directory and switch to it. 
    git switch -c  forFixV2.0.0         # Create a branch named forFixV2.0.0 and switch to it.

  3. (Optional) If the new branch is modified, commit the changes to the repository of the branch. 
    git add .                           # Add the changes to the temporary zone of the new branch.
git commit -m "fix bug for V2.0.0"  # Save the changes to the repository of the branch.

  4. Switch to the master branch and merge the new branch (forFixV2.0.0 in this example) to the master branch. 
    git checkout master                # Switch to the master branch.
git merge forFixV2.0.0             # Merge the changes based on the historical version into the master branch.

    The preceding commands are used to help you understand how to obtain a historical version using a tag. Omit or add Git commands as required.

Parent topic: Managing Code Files