Git 101 - Git overview

Git 101: What is Git?

Git is a magic tool to help you track, version, and release your files.

It is easy to learn everything you need to know for day-to-day tasks, and powerful enough for automation.

Git runs on our AllSpice server and on your local machine.

Track your design changes

• Change from main to develop branch
• Create design changes on their local file system
• Commit the files to their local develop branch
  • Add a meaningful commit message
  • "Remove C237, 0.2uF bypass cap from U14
• Commits are pushed to remote branch

Review your design changes

• Create a Design Review to merge develop branch to main branch
• Team reviews changes
  • Suggest/require changes
  • Review fabrication/output files
  • Create Issues to resolve/defer action items
  • Approves design review by merging develop branch to main

Git 101: Installing Git

If you've never used Git before, then we recommend GitHub Desktop for ease of use. Your teammates might make a recommendation

• Git Bash Command Line Interface (CLI) Download
• TortoiseGit Download (File Explorer interface)
• GitHub Desktop Download (Easiest for beginners)
• Source Tree Download

Git 101: Branches

Branches organize and control change

Changes are first committed to a local branch and then are pushed to a server. Changes can't move from one branch to another without using a design review, or by manually adding them.

We recommend a two-branch strategy for hardware development.
- Main branch alway is the latest release
- Releases for V1, V2...VN
- Develop branch contains proposed changes
- All developers work on the same branch

Branch protection allows you to prevent accidental pushes or merges.

• Visit your repository settings

  • Click on the Branches menu

  • Click on "Add New Rule" to add a new rule

  • 

  • Add the name of the branch you would like to protect and configure the settings.

  • We recommend disabling push

  • 

Git 101: Design reviews

Git Design Reviews allow you to verify the file changes before you merge one branch to another. It is the equivalent to an ECO.

AllSpice.io Design Reviews are Git Pull Requests (PR) with a name more familiar to electrical engineers

Design review interface

Design Reviews have 3 main tabs

• Design Review interface
  • 
• Conversations
  • Reviews
  • Requests for change
  • Comments or instructions
  • Request for investigation
• Commits
  • Serial list of all changes
• Files Changed
  • Visual diffs of PCBs, Schematics, BOMs, and any text files

Creating a Design Review

• Visit your repo
• Click on the Design Reviews Tab
• Click on New Design Review
  • 
• Select the pull-from branch on the right. This is usually develop
  • 
• Ensure the branch on the left is your target branch. This is usually main.
• Click New Design Review
  • 
• Enter a name or title for your review
• You can create a Design Review template that will pre-populate the description with useful information and checklists. To learn more visit the main article.
• Add any Labels needed to categorize the review
• Attach milestones to track your repos
• Once everything looks ready, click Create Design Review
  • 
• Add Reviewers who will approve and be able to comment
  • 

Design Review Visual Diff (Files Changed)

The Files Changed Tab helps you review your changes.

On the left is a file tree showing which files are new, which have changes, and which have been deleted.

The file diffs are on the right.

You can create snippets to communicate any requested changes.

• View your schematic or PCB
• Click on Snippet
• Highlight the section you wish to show
• Click the "+" button
• Add your custom message
• Click "Add single comment"
  • 

To learn more Full article

Git 101: Issues

Issues are the equivalent of Action Items. You can use them to highlight work that needs to be done immediately, or use it to track work done over time.

You can attach files and have a full conversation about the issue. You can gate Deisgn Reviews from completing until certain issues have been closed.

You can create multiple issue templates and create custom interfaces.

Creating an issue

• Visit your repo

• Click on issues

• Click new issues

• If you have multiple issue templates, select your template

• Fill out the issue

• Assign Assignees, add labels, attach to milestones

• @mention your teammates
  

  • How do you use them

Git 101: Milestones

Please visit our main article on Milestones

Markdown

Markdown is a lightweight markup language with plain-text formatting syntax. Its main goal is to be easy to read and write, even when not converted to HTML. This article is written in markdown.

Visit our full markdown guide

Releases

See our full article on releases

Generating a Personal Access Token (PAT)

You will need to either use SSH or use a PAT to access AllSpice if you are using external authentication or SSO.

How to create an AllSpice authentication application access token

Git 102: Basic Git commands

We have a Git cheat sheet with more commands.

git clone [url]

git pull

git push [alias] [branch]

git switch

git status

git add [file/directory]

git commit -m "[descriptive message]"

Writing a good commit message

- Short (Under 60 characters)
- Descriptive (what did you do?)
- This will be part of the review
- Use imererative tense
- Add bypass cap
- vs "Added bypass cap"

Git 102: Merge conflicts

Merge conflicts happen when two different people make changes to files on either the same branch, or different branches. When they go to merge, there will be a merge conflict.

Avoiding merge conflicts

The best way to deal with merge conflicts is by prevention.
- Set up branch protection on main
- Separate schematics into multiple files
- Communicate when working on single files like the PCB
- Use LFS to lock files

Fixing merge conflicts

Although we're building a merge engine, for now, the best way to fix a merge conflict is to view the file changes in AllSpice and manually copy the changes to the new file.

Quick links and resources

• Todo before your onboarding
• learn.allspice.io
• AllSpice Crash Course
• AllSpice Support contact: Daniel Lindmark
  • support@allspice.io or daniel@allspice.io
• Selected AllSpice Blogs:
  • Design Reviews
  • Git for Hardware revision control
  • Pushing & Branching

Teams and role-based permissions

Visit our main article on teams