admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

branches

Browse source
This commit is contained in:
Julie Kirsch 2024-11-04 14:39:16 +01:00
parent f2db5de663
commit 93090ee2d6
3 changed files with 109 additions and 131 deletions
Download patch file Download diff file Expand all files Collapse all files

179
book/workflows/branches.md
View file

@ -21,66 +21,15 @@ The act of making a new branch from an existing one is called *branching*. Usual
``````{tab-item} ... GitLab
1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
:name: new-branch-button
Click the highlighted button to make a new branch.
```{include} new_branch_gitlab.md
```
2. A new page opens ({numref}`new-branch-menu`), on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
```{figure} ../images/gitlab-branch-name.png
:name: new-branch-menu
We're making a new branch called `chapter-2` from the `main` branch.
```
3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch which is what we previously called `selecting an existing version`.
```{figure} ../images/gitlab-new-branch-repo.png
:name: new-branch-repo
The circled menu is the branch selection menu.
```
``````
``````{tab-item} ... GitHub
How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```{include} new_branch_github.md
```
1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
<figure align="center">
<img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
</figure>
3. Finally, give your branch a name and specifiy the source branch. <br>
Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
<figure align="center">
<img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
</figure>
4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).
<figure align="center">
<img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
</figure>
``````
```````
``````````
@ -103,11 +52,13 @@ If your repository is already cloned on your computer, you are almost ready to s
``````{tab-item} ... GitLab
1. Navigate to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
1. Navigate to the repository of your book. Click on the blue button that says "Clone", and copy the link under "Clone with SSH".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
---
name: gitlab-clone
---
The cloning menu.
```
``````
@ -116,36 +67,50 @@ The cloning menu.
1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
```{figure} figures/NewBranch_GitHub.PNG
---
name: NewBranch_GitHub1
---
Overview
```
2. Clicking on the button will display the following screen. Make sure the option `SSH` is selected and copy the link.
<figure align="center">
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
</figure>
``````
```{figure} figures/Clone_GitHub.PNG
---
name: Clone_GitHub
---
Clone using SSH
```
``````{tab-item} ... GitHub through GitHub Desktop
1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
```{figure} figures/NewBranch_GitHub.PNG
---
name: NewBranch_GitHub2
---
Overview
```
2. Clicking on the button will display the following screen. Click on `Open with GitHub Desktop`.
<figure align="center">
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
</figure>
```{figure} figures/Clone_GitHub.PNG
---
name: Clone_GitHub1
---
Clone using SSH
```
3. The Browser should then automatically open GitHub Desktop. Customize the path to the location where you would like to save to files locally. Finally, click on `Clone`.
<figure align="center">
<img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
</figure>
```{figure} figures/CloneRepo_TroughGithubdesk.PNG
---
name: CloneRepo_TroughGithubdesk.PNG
---
Clone through GitHub Desktop
```
You have now directly cloned the repository, so you can skip the next step!
``````
@ -154,9 +119,10 @@ You have now directly cloned the repository, so you can skip the next step!
**(b) ... and opening (cloning) the local repository with ...**
```````{tab-set}
``````{tab-item} ... VS Code
1. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
1. Open a new VS Code window. You should be greeted with a welcome page. On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
@ -197,71 +163,20 @@ Have a look at the other section!**
**(a) by creating my own version (branching) or select an existing version (checkout branch) ...**
Although it is possible to create new branches in VS Code directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed to the remote repository.
Although it is possible to create new branches in VS Code or GitHub Desktop directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed/published to the remote repository.
`````{tab-set}
````{tab-item} ... in GitLab
1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
:name: new-branch-button
Click the highlighted button to make a new branch.
```{include} new_branch_gitlab.md
```
2. A new page opens ({numref}`new-branch-menu`), on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
```{figure} ../images/gitlab-branch-name.png
:name: new-branch-menu
We're making a new branch called `chapter-2` from the `main` branch.
```
3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`.
```{figure} ../images/gitlab-new-branch-repo.png
:name: new-branch-repo
The circled menu is the branch selection menu.
```
````
````{tab-item} ... GitHub
How to branch is demonstrated in the figure below, followed by a step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```{include} new_branch_github.md
```
1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
<figure align="center">
<img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
</figure>
3. Finally, give your branch a name and specifiy the source branch. <br>
Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
<figure align="center">
<img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
</figure>
4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version).
<figure align="center">
<img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
</figure>
````
`````
@ -279,14 +194,16 @@ In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-m
Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
---
name: git-branch-menu-main
---
Location of the branch menu.
```
```{figure} ../images/git-branch-selection-menu.png
:name: git-branch-selection-menu
---
name: git-branch-selection-menu
---
The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch.
```

39
book/workflows/new_branch_github.md Normal file
View file

@ -0,0 +1,39 @@
How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```
1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`.
```{figure} figures/NewBranch_GitHub.PNG
Overview
```
2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
```{figure} figures/NewBranch_GitHub2.PNG
Overview Branches
```
3. Finally, give your branch a name and specifiy the source branch. <br>
Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
```{figure} figures/NewBranch_GitHub3.PNG
---
width: 60%
---
New Branch
```
4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).
```{figure} figures/NewBranch_GitHub4.PNG
Select New Branch
```

22
book/workflows/new_branch_gitlab.md Normal file
View file

@ -0,0 +1,22 @@
1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it. Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
Click the highlighted button to make a new branch.
```
2. A new page opens, on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
```{figure} ../images/gitlab-branch-name.png
---
width: 80%
---
We're making a new branch called `chapter-2` from the `main` branch.
```
3. You should be sent back to an overview page of your repository. In the branch selection menu, it should now say `chapter-2` instead of `main`.
```{figure} ../images/gitlab-new-branch-repo.png
The circled menu is the branch selection menu.
```