How does refile work?

[Maltimore]

I'm doing <Leader>or to refile a subtree, but whatever I do, nothing happens (no error message either). How to use this?

1. Does it refile the subtree to another heading in the same org file, or to another org file?
2. What do I need to enter at the prompt Enter destination: after doing <Leader>or? I've tried destinations that are the names of other org files (I've tried relative paths and absolute paths), and I've tried destinations that are other headlines. Nothing produced a result.

[jgollenz]

1. That depends on which file you specify. You can refile to the current file and target a different heading
2. You enter the file you want to refile to, slash, the heading you want to target: file.org/my_heading

I might be wrong about this, but it looks like the target file needs to be in the same directory as the source file. There is no way to specify nested headings, you just specify the heading name. If there are multiple headings with the same name, the first one will be taken. If you use an autocomplete engine, the available headlines and files will be suggested to you

[Maltimore]

Thank you! I'm not using a completion engine (unless the supertab plugin is a completion engine?). But now that I've tried a bit more, it turns out that I can tab-complete org files that are listed in the org_agenda_files setting. When I select a tab-completed file and headline, refiling works great (thanks again!). But refiling to a file that is not part of org_agenda_files does not work still. Even when I type out the file name and headline completely, and both files are in the same directory, and vim is open in that directory.

[jgollenz]

@kristijanhusak how does this work? Is it only possible to refile to files you specified in org_agenda_files? I assume so, as this is also the behavior I found.

@Maltimore my org_agenda_files has this value: path/to/my/org-files/*
This way it finds any file in that directory, but I think it only works for .org files nevertheless.

PS: I was just about to add a simple error message for the case one specifies a file that cannot be found, but I found out that trying to refile to a correct file with an incorrect headline produces a bug. Going to investigate further

[kristijanhusak]

@jgollenz yeah, only files that are part of org_agenda_files.