HTTPS clone URL
Subversion checkout URL
How to Hack on Brackets
- [archives] Health report data aug 2015
- [archives] Health report data jul 2015
- API Cleanup Ideas
- Areas of Expertise
- Brackets 5 15 2012 Hackathon Notes
- Brackets CodeMirror v4 Migration Guide
- Brackets Coding Conventions
- Brackets Committer Policy
- Brackets Communication Channels
- Brackets Community Testing
- Brackets Developers Guide
- Brackets Development How Tos
- Brackets Extensions
- Brackets in Browser
- Brackets JSDocs Guidelines
- Brackets Node Process: Overview for Developers
- Brackets Screenshots
- Brackets Server Smoke Tests
- Brackets shell command line arguments (proposal)
- Brackets Shortcuts
- Brackets Smoke Tests
- Building Brackets Releases
- Building CEF and Chromium
- Cache Folder
- CEF Debugging
- CEF3 vs. Chromium Content Shell
- Code Hinting API Investigation
- Code Hinting Functional Specifications
- CodeMirror v4 Integration
- Collecting End of Sprint Stats
- Command Line Arguments
- Commands, Menus and Shortcuts Implementation
- Contributing to Brackets
- Crash Logs
- Creating and Posting Brackets Hotfix Releases
- Creating Themes
- CSS Context API implementation spec
- CSSUtils, HTMLUtils
- Customize Your Code Font
- Debugging Brackets
- Debugging Test Windows in Unit Tests
- Dependency Analysis
- Extension API Research
- Extension Dependencies
- Extension Experiments
- Extension Icon Guidelines
- Extension Locations
- Extension Manager Workflows
- Extension package format
- Extension Package Manager Research
- Extension Registry Architecture
- Extension Registry Help
- Extension Repository Server API
- Extension Robustness
- Extension Testing Recommendations for SplitView
- Extension UI Guidelines
- Extension Unit Tests
- File System
- File System API Migration
- File System Implementations
- File system watcher requirements
- Generating Brackets API Docs
- Google Summer of Code 2013 Project Ideas
- Grunt Setup
- Health Data
- Health Report Data
- How to Hack on Brackets
- How to Report an Issue
- How to Use Brackets
- How to write extensions
- Inline Color Editor
- Issue Clusters 1.0 Milestone
- Keyboard Shortcuts
- Language Support
- Language Support Changes
- Large Projects
- Linux Development for Contributors
- Linux Version
- Live Development: lifecycle research and future directions
- Live Preview API
- Live Preview Multibrowser
- Live Preview Overview
- Live Preview URL Mapping
- Localization Tests
- Migrating or Syncing Brackets Configuration
- New Code Hinting API Proposal
- Notes on CodeMirror
- Performance Profiling
- Performance Testing
- Performance Tests Procedure
- Preferences Code Hints for Developers
- Preferences Overview
- Preferences System
- Preview Images Research old drafts
- Preview Images Spec
- Programmatically Opening Files in Brackets
- Pull Request Checklist
- Pull Request Process
- Pull Request Review Checklist
- Related Documents
- Release Notes
- Release Notes: 0.40
- Release Notes: 0.41
- Release Notes: 0.42
- Release Notes: 0.43
- Release Notes: 0.44
- Release Notes: 1.0
- Release Notes: 1.1
- Release Notes: 1.2
- Release Notes: 1.3
- Release Notes: 1.4
- Release Notes: 1.5
- Release notes: sprint 10
- Release notes: Sprint 11
- Release notes: Sprint 12
- Release notes: Sprint 13
- Release notes: Sprint 14
- Release Notes: Sprint 15
- Release Notes: Sprint 16
- Release Notes: Sprint 17
- Release Notes: Sprint 18
- Release Notes: Sprint 19
- Release Notes: Sprint 20
- Release Notes: Sprint 21
- Release Notes: Sprint 22
- Release notes: sprint 23
- Release Notes: Sprint 24
- Release Notes: Sprint 25
- Release Notes: Sprint 26
- Release Notes: Sprint 27
- Release Notes: Sprint 28
- Release Notes: Sprint 29
- Release Notes: Sprint 30
- Release Notes: Sprint 31
- Release Notes: Sprint 32
- Release Notes: Sprint 33
- Release Notes: Sprint 34
- Release Notes: Sprint 34.1
- Release Notes: Sprint 35
- Release Notes: Sprint 36
- Release Notes: Sprint 37
- Release Notes: Sprint 38
- Release Notes: Sprint 39
- Release Notes: Sprint 7
- Release Notes: Sprint 8
- Release notes: sprint 9
- Research: CodeMirror document linking
- Research: Design Alternatives for Split View
- Research: Drag and Drop from Finder
- Research: Extension Management
- Research: Find Replace
- Research: HTML DOM Data Structure
- Research: jQuery 2.0 Upgrade
- Research: Multiple cursors and selections
- Research: Node.JS Integration
- RESEARCH: Preference Format
- Research: Simplified LESS Support
- Research: Topcoat
- Running Brackets Unit Tests
- Running Jasmine tests from the command line for Linux
- Simple "Hello World" extension
- Spec: Native Installers
- SplitView Architecture Notes
- SplitView Architecture Tasking
- SplitView Extension Migration Guide
- SplitView Proposed Architecture
- Suggest a Feature
- Tech Summit Product Fair Brackets
- Testing Brackets
- Testing Pritam's Linux build
- Translations community assistance
- Typing Speed Mini Spec
- Upgrading CodeMirror from Upstream
- User Key Bindings
- Using File Filters
- Working with fsevents_win.node
- Working with Multiple Selections
- ZZZ (OBSOLETE) CodeMirror v3 integration
- افزونه ها در براکتس به چه معناست؟
- براکتس چیست؟
Clone this wiki locally
This page is mainly about modifying core Brackets code. If you're adding a new feature, consider writing an extension instead.
If you're interested in submitting a pull request, review the guidelines for contributing code. Most importantly:
- Discuss any major changes or questions beforehand in the brackets-dev newsgroup.
- Follow the Pull Request Checklist to ensure a good-quality pull request.
- Sign the Brackets Contributor License Agreement (CLA) — we can't merge your code otherwise. You only need to do this once.
- Latest Brackets installer build (or if you'd rather build the native bits yourself instead, see below).
- Git command line tools — follow the setup instructions on GitHub or download here
- Install the latest Brackets build (this gives you the native shell binaries which you'll use in step 6)
- Fork the brackets repo
- Clone your fork of the repo:
git clone https://github.com/<username>/brackets.git
- Fetch submodules:
git submodule update --init
- Add an "upstream" remote:
git remote add upstream https://github.com/adobe/brackets.git
tools\setup_for_hacking.bat "C:\Program Files (x86)\Brackets"
(MUST be run in a Command Prompt started with "Run as Administrator")
sudo tools/setup_for_hacking.sh "/opt/brackets"
Now, when you launch the Brackets app it will load your git copy of the source code, rather than the original source code that was distributed with the installer. It will share the same preferences & set of installed extensions that a regular installed build would use.
Making changes is simple:
- Edit the source code and save your changes (you can even do this with Brackets)
- Choose Debug > Reload With Extensions to reload Brackets and pick up the changes. No build step is needed.
For more in-depth instructions see "Getting a Copy of the Code" below.
For hacking on the native code or building the app binaries yourself without running an installer, see "Hacking on brackets-shell" below.
- API docs: http://brackets.io/docs/current (also inline in the code as JSDoc comments)
- Use Dev Tools to debug Brackets
- Core APIs & architecture overview
- How to use common APIs
- Make sure your local copy of source is up to date:
git fetch upstream && git merge upstream/master
- Make sure submodules are up to date:
git submodule syncand
git submodule update --init
- Create a feature/bugfix branch:
git checkout -b <branchname>
- Hack on Brackets!
- Commit your changes:
git commit -am "Your commit message here"
- Run unit tests
- Push changes to your fork of the repo:
git push origin <branchname>
- Make sure you've reviewed the Pull Request Checklist and signed the Contributor Licence Agreement (CLA). (See also overall guidelines for contributing code).
- Submit pull request on GitHub, including a descriptive title and links to any relevant bugs you're fixing.
Brackets is primarily built in HTML/JS/CSS, but it currently runs as a desktop app inside a thin native app shell called brackets-shell, based on CEF, that lets it access local files. (It doesn't run in the browser yet, but we're hoping to work on an in-browser version soon.)
The HTML/JS/CSS files are installed along with brackets-shell, but you can set up a separate development copy of these files and then load them in brackets-shell instead of the default installed copy. See Running Your Copy of the Code for more details.
For details on working with Brackets's architecture and APIs, see Brackets Development How-Tos.
Whatever you want, of course! Check out the CONTRIBUTING guide for some ideas.
If you're planning to do something other than a small bugfix, please start a discussion on the brackets-dev Google group or the #brackets IRC channel on freenode to get feedback. There might already be some prior thinking on what you're working on, or some reason that it hasn't already been done. We don't want you to do tons of work and then have to rewrite half of it.
First, sign the Brackets Contributor License Agreement (CLA). This is for your protection as well as that of the Brackets project.
Then, just submit changes as pull requests from your own fork of brackets or brackets-shell. The core dev team works in 2.5-week sprints (weird length, but it works for us). We'll try to review small pull requests quickly in the current sprint. Larger submissions may take longer — but discussing them in advance will smooth the process!
Before you submit your pull request, please make sure it's merged with master and fully tested as described in the Pull Request Checklist.
Note: Don't use the GitHub "ZIP" to get a copy of the source. The auto-generated ZIP file will be missing important dependencies.
The first step is to fork the repo on GitHub so you can start making changes in your local repository. For the HTML/JS/CSS code that comprises the bulk of Brackets, you only need to fork the brackets repo. (See "Hacking on brackets-shell" below if you want to work on the native code as well). To fork a repo, simply click the "Fork" button at the top of the page.
Next pull the repositories down to your local machine.
git clone https://github.com/<your username>/brackets.git cd brackets git submodule update --init
Don't skip the last line! Brackets uses submodules for third-party dependencies (like CodeMirror), so it won't work until you run this command to set them up.
You may also need to run
git submodule updatewhen you switch branches or pull from upstream, since submodule changes aren't updated automatically. If you see third-party code showing up as modified in
git status(something like
M src/thirdparty/CodeMirror2), then you need to run this command.
If you're only hacking on HTML/JS/CSS files, you can have the installed Brackets shell run your local copy of the HTML/JS/CSS code (instead of the default installed copy) by running the
tools/setup_for_hacking script. Here's how:
- Download and install the latest Brackets sprint build.
- Follow "Getting a Copy of the Code" above to fork & clone the brackets repo.
- On a Mac:
- Open a Terminal window
cdto the root of your brackets repo
tools/setup_for_hacking.sh, passing the full pathname to your installed Brackets.app. For example:
- On Windows:
- Open a Command Prompt using "Run as Administrator"
cdto the root of your brackets repo
tools\setup_for_hacking.bat, passing the full path of the directory where Brackets.exe is installed. For example:
tools\setup_for_hacking.bat "C:\Program Files (x86)\Brackets"
- Launch the installed copy of Brackets, select Help > About, and verify that the version number says "sprint xx development build" instead of "sprint xx experimental build". This indicates that you're running Brackets from your git repo instead of the installed build.
You can revert back to running the installed version of the Brackets source at any time by running
tools/restore_installed_build.sh (Mac) or
tools\restore_installed_build.bat (Windows) from your Brackets repo.
Once you are set up, Brackets will pick up the latest changes to the code every time it starts — no build step is needed. (The Grunt scripts are used only to generate a final release build).
It's important to keep up to date with the main Brackets repository to make sure your pull requests match the latest Brackets builds. First you'll first need to link your local clone of Brackets to track the main Brackets repository on GitHub. Run this command from the brackets directory:
cd brackets git remote add upstream https://github.com/adobe/brackets.git
Your repo will now have two "remotes":
origin refers to your fork on GitHub, while
upstream refers to the original, official Brackets repo.
If you want to avoid getting branches other than master, you can add the
--track masterargument after
add. However, that will mean that if you need to pull a different branch, you'll need to explicitly fetch it.
Getting the latest changes on the Brackets
master branch is a two-step process. First:
git fetch upstream
This brings down any new commits into your repo, but doesn't actually update any of your branches. Next, update your current local branch:
git merge upstream/master
This merges any changes from the main Brackets repository into whichever branch you currently have checked out locally. (To update multiple local branches, you'll need to
git checkout each one in turn and repeat the merge command).
You may also need to run
git submodule update at this point — if the output of
git fetch said "Fetching submodule" or if
git status shows an unexpected diff in a third-party library.
Rarely, an entire new submodule is added to Brackets. You'll need to run
git submodule update --init when that happens.
You can see a diff before merging with
git difftool ...upstream/master.
For a higher-level overview (with API important changes called out), check the Release notes after each sprint.
If you also forked the brackets-shell repository, repeat the steps above for the brackets-shell repo, then rebuild the shell once you've pulled down updates.
If you did not fork the brackets-shell repo (i.e. you're using the 'setup_for_hacking' step above), you should update your installed build of Brackets each sprint and rerun the 'setup_for_hacking' script. This ensures you're using the latest app binaries.
If you use Brackets to edit Brackets, you can quickly reload the app itself by choosing Debug > Reload Brackets from the in-app menu. You can also debug Brackets using dev tools — but to keep Reload working properly while dev tools are open, be sure to disable caching as instructed in that link.
You can use Debug > Run Tests to run our unit test suite.
If you've found an issue you want to fix or a feature you want to implement, eventually you'll want to submit a pull request back to Brackets upstream. Here's how to organize your changes so they're ready to turn into a pull request.
First, create a new branch off of
master for the change you want to work on. This allows your
master branch to stay in sync with the main Brackets repository — and if your change doesn't work or breaks something, you can always start fresh from your local
git checkout master git branch mynewfeature git checkout mynewfeature
That creates a new branch called
mynewfeature and sets it as your working branch. Any changes you make now will be linked to that branch. While you work on it, you should still keep your branch in sync with Brackets master following the "Getting Updates from the Main Repository" steps above.
Now go ahead and modify some code, make your fix, and be sure that it works in your copy of Brackets. As always, please follow the guidelines for contributing code to ensure your code matches what's expected for Brackets contributions.
Next it's time to commit your changes to your local git repo. Use
git add <filename> to stage any modified files for committing, then use
git commit -m "COMMIT MESSAGE" to commit those files. (Or just use use
git commit -am "COMMIT MESSAGE" to commit all modified files). Be sure to write a thorough commit message that describes the changes you're making and why.
The last step before submitting a pull request is to push those changes to your GitHub account — so far the changes are only stored in your local copy of the Brackets repository. Remember that your GitHub fork of the Brackets repo is called "origin"... so to push your changes use:
git push origin mynewfeature
That command creates a matching branch on your GitHub-hosted repo and copies your branch's commits into it. Now your commits are stored on the GitHub server and not just locally.
This is a good time to review the Pull Request Checklist — make sure your code passes JSLint, doesn't break any unit tests, etc.
Now you're ready to submit a pull request. Go to the GitHub page for your fork of Brackets and choose your branch from the dropdown near the upper left (it says
master by default). Now you're looking at the code for that branch.
Click the Pull Request button in the top right and you'll be brought to a page that describes the pull request. Make sure you're submitting to the
adobe/brackets repository, from the branch you've been working on.
Review the "Commits" and "Files Changed" tabs to make sure you're submitting only the changes you intend. Write a detailed description of what your pull request does, and include links to any relevant bugs ("#1234" is automatically turned into a link — though avoid writing "fixes #1234", since GitHub will auto-close the bug too soon if it sees a string like that). Then click "Send pull request."
Congratulations on submitting your pull request — you're helping make Brackets even better! Read about the pull request review process for what happens next.
During code review, you will probably be asked to make some changes to your code. First, make sure you're working on the correct branch:
git checkout mynewfeature
Then make the necessary code changes. When done, repeat the
git commit and
git push steps from above.
Ta daa! As soon as you've pushed those changes to "origin" (your fork on GitHub), your pull request is automatically updated with the new code. Finally, add a comment to the pull request describing the new changes — this ensures the code reviewer is notified of your update.
For most of your changes to Brackets, you should only need to edit the HTML/JS/CSS code in the brackets repo. You won't need the source for brackets-shell because you can use a pre-built binary from a Brackets installer to run your modified HTML/JS/CSS code (see instructions above).
However, you may want to set up a dev environment for brackets-shell if:
- You want to hack on the native code.
You want to pull the latest from the brackets repo
masterand it requires a new brackets-shell build that hasn't been released as a binary yet. (This is uncommon, but it can happen).