Git client workflow

Clone your project files

Whether you have migrated your repositories from an existing repo [link] or you’ve initialized a new repo [link], you’re going to start by copying the clone link.

1. First, navigate to your repository page and locate the Clone URL in the top right corner. If you’re comfortable with setting up SSH click on the “SSH” button (which will skip the password entry step) otherwise select “HTTPS” and then click on the little clipboard icon to copy the Clone URL to your clipboard:

2. Now navigate to the folder you’d like to keep your AllSpice repositories. Right-click on an empty space and click on “Git Clone…”

3. Paste the text into the “URL” box by right clicking inside the white area of the box and click on “Paste”

4. When prompted input your AllSpice hub username and password and then hit “OK”.

Your files should download momentarily and a new folder will be created with the project name. All the files from your project will be located within that newly created folder.

If you are working from a new repository you’ve initialized in AllSpice Hub you should see that the repo has been initialized with a .gitignore and README.md file.

5. If you don’t see the .gitignore file, you might want to toggle Windows Explorer to show hidden files by going to “View” → “Options” → Change Folder Options → “View” → Show hidden files, folders, and drives. This isn’t required but will help in later steps.

Checking out a branch

Before jumping in and making changes to your project files we need to make sure to get on the correct branch. A best practice for using Git, or most version control systems, is to never commit directly to the main branch unless absolutely necessary (admins can actually set up branch protection to prevent this). In software engineering, the concept of the main branch is to have code that is always approved. If people committed their broken code to the main branch then others checking out the repository (via the main branch by default) would not be able to execute or compile the shared code. As a result, teams use what’s called a branching scheme. Each individual or group of engineers will work on development branches and then merge those branches into main after a design review or Pull Request.

The same concept can be used within electronics design as well. Rather than push our latest changes of an incomplete or messy design to the main branch we can commit our work to development branches while keeping the main branch pristine with a design that has passed a design review. By default, AllSpice will create two branches for you when you have it initialize a repository for you (which is the default option): main and develop.

Let’s go ahead and check out the develop branch since that’s where we should be committing our work to.

6. Right-click on the project folder or any empty space within the project folder itself and navigate to TortoiseGit > Switch/Checkout…

7. Under the Branch drop-down menu select “remotes/origin/develop” and click on OK.

You are now ready to make your first commit.

Setting up your directory

8. The next thing to do is copy over the files you want to revision or create a new project in the directory you’ve cloned.

The “?” icon indicates that these files are not yet part of your history. Let's fix that!

Pushing Your Changes

After you’ve made changes to your design you’re going to want to send the updates back to the AllSpice hub. In Git this is a two-stage process: Commit and Push. Commit does all the revisioning, commenting, and all the goodness that comes with a version control system and then stores it locally. The Push action simply takes what you have on your computer and uploads that to the server. Luckily with TortoiseGit, we can combine it into a single step. Once you’re ready to push your files to the AllSpice Hub, navigate to your project folder, right-click on an empty space, and click on “Git Commit.”

9. To add them to the git repository you can right-click on the project folder or any empty space within the project folder itself and navigate to TortoiseGit > Git Commit…

10. Select all of the files you want to keep in revision control and either check them or right-click and select “Add”. Note that you should be committing to “develop”. You are required to input a message to your commit.

11. Once you’re all set, select the dropdown and “Commit & Push”. If you’d like to split this up, you can always “push” in the next step.

Viewing updates

12. Now let's take a look at the current state. Right-click on the project folder or any empty space in windows explorer to navigate to the log with TortoiseGit > log.

13. At the bottom, you should see an option to view “All Branches”. Check this.

You’ll see the following branches: develop, origin/develop, main, origin/main, and origin/HEAD.

In general, origin references the remote git server (i.e. AllSpice Hub). After the slash is the remote branch.

The develop branch is your local copy (clone) of origin/develop highlighted red, indicating it is the current branch you are checked out to. The origin/HEAD one is a special pointer used to indicate the “default” remote branch (you shouldn’t have to worry about this).

14. Head back to your repository in AllSpice Hub. By default, you’ll see your main branch without your new files.

15. Let's bring those over by starting a design review. Go to Branch: develop

16. The easiest way to bring your main branch up to date with your develop branch is to start a new design review. Select “New Design Review”, and you’ll see all of your files are highlighted green, indicating they are added.

17. Press the new button for “New Design Review” to confirm.

18. Finally, add some notes and select “Create Design Review”.

19. Here, you have a chance to check that everything looks good before you merge it into main. If so, go ahead and hit the “Merge Files” button.

20. If you realize you want to make some changes, you can head back to your local repository and commit + push any new changes to the develop branch. Once you reload the design review, you’ll see those changes have been updated.

Now you should see your main branch has the latest files!