Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).

# Organizing your source code work with branches in Amazon CodeCatalyst
<a name="source-branches"></a>

In Git, branches are pointers or references to a commit. In development, they're a convenient way to organize your work. You can use branches to separate work on a new or different version of files without affecting work in other branches. You can use branches to develop new features, store a specific version of your project, and more. You can configure rules for branches in source repositories to limit certain actions on a branch to specific roles in that project.

Source repositories in Amazon CodeCatalyst have contents and a default branch regardless of how you create them. Linked repositories might not have a default branch or content, but are not usable by CodeCatalyst until you initialize them and create a default branch. When you create a project using a blueprint, CodeCatalyst creates a source repository for that project that includes a README.md file, sample code, workflow definitions, and other resources. When you create a source repository without using a blueprint, a README.md file is added for you as a first commit, and a *default branch* is created for you. This default branch is named *main*. This default branch is the one used as the base or default branch in local repositories (repos) when users clone the repository.

**Note**  
You can't delete the default branch. The first branch created for a source repository is the default branch for that repository. Additionally, search only displays results from the default branch. You can't search for code in other branches.

Creating a repository in CodeCatalyst also creates a first commit, which creates a *default branch* with a README.md file included in it. The name of that default branch is *main*. This is the default branch name used in the examples in this guide. 

**Topics**
+ [Creating a branch](source-create-delete-branch.md)
+ [Managing the default branch for a repository](source-branches-default-branch.md)
+ [Manage allowed actions for a branch with branch rules](source-branches-branch-rules.md)
+ [Git commands for branches](source-branches-git.md)
+ [Viewing branches and details](source-branches-view.md)
+ [Deleting a branch](source-branches-delete.md)

# Creating a branch
<a name="source-create-delete-branch"></a>

You can use the CodeCatalyst console to create branches in a CodeCatalyst repository. The branches you create will be visible to other users the next time they pull changes from the repository. 

**Tip**  
You can also create branches as part of creating a Dev Environment to work on your code. For more information, see [Creating a Dev Environment](devenvironment-create.md).

You can also use Git to create branches. For more information, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table).

**To create a branch (console)**

1. In the CodeCatalyst console, navigate to the project where your source repository resides.

1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**.

1. Choose the repository where you want to create a branch.

1. On the overview page of the repository, choose **More**, and then choose **Create branch**.

1. Enter a name for the branch.

1. Choose a branch to create the branch from, and then choose **Create**. 

# Managing the default branch for a repository
<a name="source-branches-default-branch"></a>

You can specify which branch to use as the *default branch* in a source repository in Amazon CodeCatalyst. All source repositories in CodeCatalyst have contents and a default branch regardless of how you create them. If you use a blueprint to create a project, the default branch in the source repository created for that project is named *main*. The contents of the default branch are displayed automatically on the overview page for that repository.

**Important**  
CodeCatalyst doesn't support detecting changes in the default branch for linked repositories. To change the default branch for a linked repository, you must first unlink it from CodeCatalyst, change the default branch, and then link it again. For more information, see [Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-link.md).  
As a best practice, always make sure you have the latest version of the extension before you link a repository.

The default branch is treated a little differently than all other branches in a source repository. It has a special label next to its name, **Default**. The default branch is the one used as the base or default branch in local repositories (repos) when users clone the repository to local computers with a Git client. It is also the default used when creating workflows for storing workflow YAML files, and for storing information for issues. When using search in CodeCatalyst, only the default branch of a repository is searched. Because the default branch is fundamental to so many aspects of projects, you cannot delete a branch if it is specified as the default branch. However, you can choose to use a different branch as the default branch. If you do, any [branch rules](source-branches-branch-rules.md) that were applied to the former default branch will be applied automatically to the branch you specify as the default branch.

**Note**  
You must have the Project administrator role to change the default branch for source repositories in CodeCatalyst projects. This does not apply to linked repositories.

**To view and change the default branch for a repository**

1. Navigate to the project where your repository resides.

1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**.

   Choose the repository where you want to view the settings, including the default branch.

1. On the overview page of the repository, choose **More**, and then choose **Manage settings**.

1. In **Default branch**, the name of the branch specified as the default branch is displayed along with a label called **Default** next to the name. This same label appears next to the branch name in the list of branches in **Branches**.

1. To change the default branch, choose **Edit**.
**Note**  
You must have the Project administrator role in the project to change the default branch.

1. Choose the name of the branch you want to make the default branch from the drop-down list and then choose **Save**.

# Manage allowed actions for a branch with branch rules
<a name="source-branches-branch-rules"></a>

When you create a branch, certain actions are allowed for that branch based on the permissions for that role. You can change what actions are allowed for a specific branch by configuring branch rules. Branch rules are based on the role a user has in your project. You can choose to limit some predefined actions, such as pushing commits to a branch, to users with a particular role in a project. This can help you protect specific branches in a project by limiting which roles are allowed to perform certain actions. For example, if you configure a branch rule to only allow users with the **Project administrator** role to merge or push to that branch, users with other roles in the project will not be able to make changes to the code in the that branch. 

You should carefully consider all the implications of creating a rule for a branch. For example, if you choose to limit pushes to a branch to users with the **Project administrator** role, users with the **Contributor** role will not be able to create or edit workflows in that branch, because the workflow YAML is stored in that branch, and those users cannot commit and push changes to the YAML. As a best practice, test any branch rules after you create them in order to make sure that they do not have any impacts that you did not intend. You can also use branch rules in conjunction with approval rules for pull requests. For more information, see [Managing requirements for merging a pull request with approval rules](source-pull-requests-approval-rules.md).

**Note**  
You must have the Project administrator role to manage branch rules for source repositories in CodeCatalyst projects. You cannot create branch rules for linked repositories.  
You can only create branch rules that are more restrictive than the default permissions for the role. You cannot create branch rules that are more permissive than what a user's role in the project allows. For example, you cannot create a branch rule that allows users with the Reviewer role to push to the branch.

Branch rules that are applied to the default branch of your source repository will behave a little differently than branch rules applied to other branches. Any rule applied to the default branch will be automatically applied to any branch you specify as the default branch. The branch that was formerly set as the default branch will still keep the rules applied to it, except that it will no longer have protection against deletion. That protection is only applied to the current default branch.

Branch rules have two states, **Standard** and **Custom**. **Standard** indicates that the actions allowed on a branch are those that match the permissions for the role the user has in CodeCatalyst for branch actions. To learn more about what roles have which permissions, see [Granting access with user roles](ipa-roles.md). **Custom** indicates that one or more branch actions have actions that have a specific list of roles allowed to perform that action that differ from the default permissions granted by a user's roe in the project. 

**Note**  
If you create a branch rule to restrict one or more actions for a branch, the **Delete the branch** action is automatically set to only allow users with the Project administrator role to delete that branch.

The following table lists the actions and the default settings for roles allowed to perform these actions on a branch.


**Branch actions and roles**  

| **Branch action** |  Roles allowed to perform this action when no branch rules are applied  | 
| --- | --- | 
|  Merge to the branch (this includes merging a pull request to the branch)  |  Project administrator, Contributor  | 
|  Push to the branch  |  Project administrator, Contributor  | 
|  Delete the branch  |  Project administrator, Contributor  | 
|  Delete the branch (default branch)  |  Not allowed  | 

 You cannot delete branch rules, but you can update them to allow actions from all the roles that would be allowed to perform this action on a branch, which effectively removes the rule.

**Note**  
You must have the Project administrator role to configure branch rules for source repositories in CodeCatalyst projects. This does not apply to linked repositories. Linked repositories do not support the branch rules in CodeCatalyst.<a name="view-edit-branch-rules"></a>

**To view and edit branch rules for a repository**

1. Navigate to the project where your repository resides.

1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**.

   Choose the repository where you want to view branch rules.

1. On the overview page of the repository, choose **Branches**.

1. In the **Branch rules** column, view the status of rules for each branch of the repository. **Standard** indicates that the rules for branch action are the default ones for any branch created in a source repository and match the permissions granted to those roles in a project. **Custom** indicates that one or more branch actions have rules that restrict one or more actions allowed for that branch to a different set of roles.

   To view the specifics of the branch rules for a branch, choose the word **Standard** or **Custom** next to the branch you want to review. 

1. To create or change a branch rule, choose **Manage settings**. On the settings page for the source repository, in **Branch rules**, choose **Edit**.

1. In **Branch**, choose the name of the branch for which you want to configure a rule from the drop-down list. For each of the allowed action types, choose the roles you want to allow to perform that action from the drop-down list, and then choose **Save**.

# Git commands for branches
<a name="source-branches-git"></a>

You can use Git to create, manage, and delete branches in the clone of the source repository you have on your computer (your local repo) or in your Dev Environments, and then commit and push your changes to your CodeCatalyst source repository (the remote repository). For example: 


**Common Git commands for branches**  

|  |  | 
| --- |--- |
|  Lists all branches in the local repo with an asterisk (`*`) displayed next to your current branch.  |  `git branch`  | 
|  Pulls information about all existing branches in the remote repository to the local repo.  |  `git fetch`  | 
|  Lists all branches in the local repo and remote tracking branches in the local repo.  |  `git branch -a`  | 
|  Lists only remote tracking branches in the local repo.  |  `git branch -r`  | 
|  Creates a branch in the local repo using the specified branch name. This branch will not appear in the remote repository until you commit and push the change.  |  `git branch branch-name`  | 
|  Creates a branch in the local repo using the specified branch name, and then switches to it.  |  `git checkout -b branch-name`  | 
|  Switches to another branch in the local repo using the specified branch name.  |  `git checkout other-branch-name`  | 
|  Pushes a branch from the local repo to the remote repository using the local repo's specified nickname for the remote repository and the specified branch name. Also sets up upstream tracking information for the branch in the local repo.  |  `git push -u remote-name branch-name`  | 
|  Merges changes from another branch in the local repo to the current branch in the local repo.   |  `git merge from-other-branch-name`  | 
|  Deletes a branch in the local repo unless it contains work that has not been merged.   |  `git branch -d branch-name`  | 
|  Deletes a branch in the remote repository using the specified nickname the local repo has for the remote repository and the specified branch name. (Note the use of the colon (`:`).) Alternatively, specify `--delete` as part of the command.  | `git push remote-name :branch-name` `git push remote-name --delete branch-name`  | 

For more information, see your Git documentation.

# Viewing branches and details
<a name="source-branches-view"></a>

You can view information about remote branches in Amazon CodeCatalyst, including specifics of the files, folders, and most recent commit for a specific branch, in the Amazon CodeCatalyst console. You can also use Git commands and your local operating system to view this information for remote and local branches.<a name="source-branches-view-console"></a>

**To view branches (console)**

1. In the CodeCatalyst console, navigate to the project that contains the source repository where you want to view branches. Choose **Code**, choose **Source repositories**, and then choose the source repository.

1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**.

   Choose the repository where you want to view a branch.

1. The default branch of the repository is displayed. You can see a list of files and folders in the branch, information about the most recent commit, and the contents of the README.md file, if it exists in the branch. To view the information for a different branch, choose it from the drop-down list of branches for the repository.

1. To view all the branches for a repository, choose **View all**. The Branches page displays information about the name, most recent commit, and rules for each branch.

For information about how to use Git and your operating system to view branches and details, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table), your Git documentation, and your operating system documentation.

# Deleting a branch
<a name="source-branches-delete"></a>

If you no longer need a branch, you can delete it. For example, if you've merged a branch with a feature change into the default branch and that feature has been released, you might want to delete the original feature branch, as the changes are already part of the default branch. Keeping the number of branches low can help users find the branch that contains the changes they want to work on. When you delete a branch, copies of that branch remain in the clones of the repository on local computers until users pull and synchronize those changes.<a name="source-branch-delete"></a>

**To delete a branch (console)**

1. Navigate to the project where your repository resides.

1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**.

   Choose the repository where you want to delete a branch.

1. On the overview page of the repository, choose the drop-down selector next to the branch name, and then choose **View all**.

1. Choose the branch that you want to delete and then choose **Delete branch**.
**Note**  
You cannot delete the default branch for a repository.

1. A confirmation dialog box appears. It shows the repository, number of open pull requests, and number of workflows associated with the branch. 

1. To confirm deletion of the branch, type **delete** into the text box, and then choose **Delete**.

You can also use Git to delete branches. For more information, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table).