github.com/claudiodangelis/banco@v0.0.0-20231219182139-c31d5d844fe5/README.md (about) 1 # Banco 2 3 Banco Management System, or simply **Banco**, is an opinionated project management tool for the command line that helps you **organize notes, tasks, bookmarks and documents** for your projects. 4 5 Banco objects _(notes, tasks, bookmarks, etc)_ are stored in the **filesystem**, implemented as plain text files and folders within the root of the project, so you won't need to install or run any database or server. This enables you to easily create archives and backups, move projects around the filesystem, use command line tools, or keep track of changes by using version control. 6 7 The name "Banco" is a tribute to [Banco Del Mutuo Soccorso](http://www.progarchives.com/artist.asp?id=36), the best italian progressive rock band of all times. 8 9 10 ## Installation 11 12 You can install Banco with Go: 13 ```sh 14 go get github.com/claudiodangelis/banco 15 ``` 16 17 or by downloading the latest [binary release](https://github.com/claudiodangelis/banco/releases). 18 19 ## Configuration 20 21 Banco needs almost no configuration to get started. You only need to make sure that the following environment variables are set: 22 23 - `$EDITOR` 24 - `$BROWSER` 25 - `$FILEMANAGER` (this is optional, see the "documents" module section) 26 27 Banco will use the first to open plain text files (notes, tasks), and the second for the bookmarks. 28 29 Modules' configuration can be defined in a YAML text file which will be read by banco in the following two locations: 30 - `$HOME/config/banco.yml` 31 - `.` (current directory) 32 33 Refer to each module's section for the available configuration. 34 35 ## Modules 36 37 Banco's features are built as modules, there are modules available for management of: 38 - documents 39 - bookmarks 40 - notes 41 - tasks 42 43 and, soon, _secrets_. 44 45 A typical Banco project looks like this on the filesystem: 46 47 ```sh 48 16:14:25 /tmp/banco-test 49 $ tree -QA 50 . 51 ├── "bookmarks" 52 │ ├── "AWS" 53 │ │ └── "instances" 54 │ └── "github page" 55 ├── "documents" 56 ├── "notes" 57 │ ├── "My First Note" 58 │ └── "ideas" 59 │ ├── "discarded" 60 │ │ └── "code repositories" 61 │ └── "secrets management" 62 └── "tasks" 63 ├── "backlog" 64 │ └── "Write README" 65 ├── "doing" 66 │ └── "Take screenshots" 67 └── "done" 68 └── "Implement modules" 69 70 10 directories, 8 files 71 72 ``` 73 The above, in Banco, is rendered like this: 74 75 Root: 76 77 ![root](screenshots/banco.png) 78 79 Notes: 80 81 ![notes](screenshots/notes.png) 82 83 Tasks: 84 85 ![tasks](screenshots/tasks.png) 86 87 88 ### Notes 89 90 Notes are just plain text files stored in the `notes` folder. If you set a label for the note, it will be implemented as a subfolder of the `notes` folder. When opening a note with banco, the `$EDITOR` value will be used to open the file. 91 92 93 ### Tasks 94 95 There are two ways to represent a task: a plain text file, or a folder of files. "Tasks" module has no concept of labels, instead it uses "statuses". First-level subfolders will be considered statuses of the tasks. When you create a new task, you will be asked which one you want to create it into. By default, Banco creates `backlog`, `doing`, `done`. When opening a task with Banco, the `$EDITOR` value will be used to open the file (or the folder). 96 97 Tasks module supports the following configuration properties: 98 99 - `title` 100 101 Example configuration: 102 103 ``` 104 tasks: 105 title: "$id -" 106 ``` 107 108 Refer to the "Configuration variables" section below for a list of available variables. 109 110 ### Bookmarks 111 112 113 Just like notes, bookmarks are plain text files whose content is an URL. You can group bookmarks by labels. When opening a bookmark with banco, the `$BROWSER` value, if set, is used to open the URL. 114 Optionally, you can set the browser command and arguments in the configuration file. 115 116 #### Configuration file keys (optional) 117 118 | Key | Type | Description | 119 | --- | ---- | ----------- | 120 | `browser` | _Object_ | See below | 121 | `browser.cmd` | _String_ | Program name to use for opening bookmarks. It overrides `$BROWSER` environment variable | 122 | `browser.args` | _List of Strings_ | Program arguments | 123 124 Example 125 126 ``` 127 bookmarks: 128 browser: 129 cmd: firefox 130 args: ["-p", "work"] 131 ``` 132 133 ### Documents 134 135 Everything which cannot be organized as a note, task or bookmark is a document. When opening a document with Banco, the `xdg-open` program will be used to open the file. 136 137 **Note** since documents module is at an early stage and might be result in poor user experience, you might want to use your favorite file manager instead. To let banco use an external file manager, just set the `$FILEMANAGER` environment variable. 138 139 140 141 ## Get started 142 143 After installing Banco, create an empty folder, enter it, then run `banco init`: 144 145 ```sh 146 mkdir my-project 147 cd my-project 148 banco init 149 ``` 150 151 Banco will create the folder structure, and you will be ready to get started. 152 153 ## Command line interface 154 155 Banco uses a consistent command line interface. From the command line interface you can create, open, update, list and delete objects: 156 157 ```sh 158 banco [command] [module] 159 ``` 160 161 For example: 162 163 - Create a new note 164 165 ```sh 166 banco new note 167 ``` 168 169 You will be able to enter the title of the note and, optionally, a label. If the label doesn't exist, you can create it from there: 170 171 ![newnote](screenshots/newnote.png) 172 173 - Update a task 174 175 ```sh 176 banco update task 177 ``` 178 179 After choosing the task you want to update, you will be able to update its attributes: 180 181 ![updatetask](screenshots/updatetask.png) 182 183 184 Available commands: 185 186 | Command | Argument |Description | 187 | ---| --- | --- | 188 | `init` | | Initializes a new Banco project | 189 | `init-config` | | Initializes a configuration directory inside the current Banco project | 190 | `modules` | | List available modules | 191 | `notes` | | Shows the root of the notes module. After choosing a note, you can choose what to do with it: open, update, delete | 192 | `tasks` | | Shows the root of the tasks module. After choosing a task, you can choose what to do with it: open, update, delete | 193 | `bookmarks` | | Shows the root of the bookmarks module. After choosing a bookmark, you can choose what to do with it: open, update, delete | 194 | `documents` | | Shows the root of the documents module. After choosing a document, you can choose what to do with it: open, update, delete | 195 | `new` | `[module]` | Shows the "create" view for the module | 196 | `update` | `[module]` | Shows the "update" view for the module | 197 | `list` | `[module]` | Lists modules' items | 198 | `delete` | `[module]` | Shows the "delete" view for the module | 199 | `open` | `[module]` | Shows the "open" view for the module | 200 | `update` | `[module]` | Shows the "update" view for the module | 201 | `help` | | Prints a summary of available commands | 202 203 204 # Configuration variables 205 206 | Name | Value | 207 | --- | --- | 208 | `$id` | Replaced with the incremental number of the item to be created | 209 | `$timestamp` | Replaced with the number seconds from epoch | 210 211 # Credits 212 213 Banco is created by [Claudio d'Angelis](https://claudiodangelis.com).